What is an API

Table of Contents

APIs

API stands for application programming interface. It is a set of definitions and protocols for building and integrating application software.

APIs enable products or services to communicate with their peers without having to know their implementation. APIs can be thought of as contracts with documentation on how the software responds to requests from another software.

A vital benefit of APIs is that, they help you open access to your resources while maintaining security and control. API security is all about good API management which includes the use of an API gateway.

Cloud Native Applications and APIs

Cloud-native application development is a way of developing applications to increase development speed by connecting microservices application architecture through APIs. The cloud-native concept of building and running applications takes advantage of distributed computing provided by the cloud delivery model.

For cloud-native applications, they are designed and built to exploit the scale, elasticity, resilience, and flexibility the cloud provides. Therefore, APIs are a simplified way for a developer to connect their infrastructure through cloud-native app development as well as share their data with customers and other external users.

APIs Policies

When developing an API, the following release policies guide it:

1. Private – The API is for internal use only. The company has the most control over the API
2. Partner – The API is shared with specific business partners.
3. Public – The API is available to everyone. Third parties have the ability to develop applications that interact with the public API.

Types of APIs

Web APIs

Web APIs are the most common APIs. They provide machine readable data and transfer of functionalities between web-based systems that represent client server architecture.

These APIs use Hypertext Transfer Protocol (HTTP), to deliver requests from web applications and response messages from servers. These requests and responses take the form of a JSON file or XML

Remote APIs

Remote APIs are designed to interact through a communications network. APIs being remote means that resources being manipulated by the API are outside the computer making the request.

Whereas the internet is the most commonly used communications network and most APIs follow web standards, this does not necessarily mean that all APIs are web APIs. But the assumption is that most web APIs are remote.

Examples of Remote APIs are Java Database Connectivity API and Java Remote Method Connectivity API. For instance, you can use the Remote API library contained in the Java SDK to access Google Cloud App Engine services from any Java application.

SOAP APIs

Simple Object Access Protocol (SOAP) is a protocol specification developed to standardize the exchange of information. SOAP APIs use XML and together with schemas, they define strongly typed messaging framework.

Operations and input parameters are all codified in the Web Service Description Language (WSDL). The WSDL can be referred to as a contract between the provider and the consumer of a web service.

Sample SOAP request

POST http://www.abcde.org/fgh HTTP/1.1
Accept-Encoding: gzip, deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://www.abcde.org/Calendar#christmas_date"
Content-Length: 300
Host: http://www.abcde.org
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<?xml version="1.0"?>
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cal="http://www.abcde.org/Calendar">
<soapenv:Header/>
<soapenv:Body>
  <cal:christmas_date soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <year xsi:type="xsd:short">2023</year>
</cal:christmas_date>
</soapenv:Body>
</soapenv:Envelope>

In the above SOAP, XML server request example, the message is sent over HTTP. The message contains an Envelope, which is the single root element that contains the Header and the Body.

However, SOAP is agnostic of the underlying transport protocol since a XML message can receive requests through Hypertext Transfer Protocol (HTTP), Simple Mail Transfer Protocol (SMTP), Java Message Service (JMS) or Transmission Control Protocol (TCP).

REST APIs

REST stands for Representational State Transfer. It is the most common type of API architecture inherent to modern web applications.

Unlike SOAP which is a protocol, REST is a software architecture style that relies on a stateless communications protocol, commonly HTTP. By stateless, it means that the communication protocol does note require the server to retain session information or status about previous communications between computers or systems.

In addition, REST is very data-driven as it follows the OOP paradigm of noun-verb while SOAP is strongly function driven. Data in REST can be structured in XML, YAML, or any other machine-readable format. However, JSON is widely used.

It is important to note that there is no official web standard for RESTful web APIs. However, Roy Fielding defined APIs to be RESTful if they complied with the following guiding constraints:

1. Client-server architecture – REST architecture consists of resources, clients, and servers, and requests are handled through HTTP.
2. Statelessness – Client content is not stored on the server between requests. The client holds the information about the session state.
3. Cacheability – Some client-server interactions can be eliminated by caching.
4. Layered system – Client-server interactions can be mediated by additional layers that offer additional features like load balancing, shared caches, or security.
5. Code on demand – This is an optional constraint. Servers can extend the functionality of a client by transferring executable code.
6. Uniform interface – This is a core constraint to the design of RESTful APIs that includes the following facets:

• Resource identification in requests – Resources are identified in requests. They are separable from the representations returned to the client.
• Resource manipulation through representations – Clients receive files that represent resources. These representations should have enough information to allow modification or deletion.
• Self-descriptive messages – Each message returned to the client contains enough information to describe how the client should process the information.
• Hypermedia as the engine of application state – After a resource is accessed, the REST client should be able to discover through hyperlinks all other actions that are currently available.

GraphQL APIs

GraphQl is a query language for APIs and a runtime for fulfilling those queries with existing data. This is the newest technology in API development that was developed by Meta internally and released publicly in 2015.

GraphQL is a REST alternative that lets developers construct requests that pull data from multiple data sources in a single API call. Therefore, this prioritizes clients’ requests by giving them exactly the data they request and no more.

API developers use GraphQL to create a schema that describes all the possible data that a client can query through that service. The schema is made up of object types that define which kind of object you can request and the field it has.

When queries come in, GraphQL validates the queries against the schema. The resolver is then called during execution. From a client’s point of view, queries and mutations are the most common GraphQL operations. However, in terms of the CRUD model, a query would be equivalent to read while create, update, and delete are handled by mutations.

What Next?

In the next blog series, I will build REST, SOAP and GraphQl APIs.

Watch this space.