Getting started with APIs

What is an API?

API stands for Application Programming Interface. In the context of APIs, the word Application refers to any software with a distinct function. Interface can be thought of as a a set of definitions and protocols which define how two applications will communicate with each other. API acts as an intermediary layer which processes data transfer  between two systems.

How does an API works?

API architecture mainly consists of a client and server. The application which sends the request is called the client and the application which sends back the response is called the server. 

The client application initiates an API call to retrieve information which is also known as an API request. This request is processed from an application to the web server using the API's Uniform Resource Identifier (URI) and includes a request verb, headers and sometimes a request body. After receiving a valid request, the API makes a call to the external application or web server. The server sends a response which is also known as the API Response which contains the requested information. Finally the API transfers the data back to the client application.

Examples of APIs:

One of the good examples of API is the Google Maps service. In addition to the core APIs that display static or interactive maps, the app utilises other APIs and features to provide users with directions or points of interest. Through geolocation and multiple data layers, you can communicate with the Maps API when plotting travel routes or tracking items on the move, such as a delivery vehicle.

Different Types of APIs

There are four main types of APIs:

1. Open API: It is also known as public APIs as there are no restrictions to access these type of APIs because they are publicly available
2. Partner API: It is not available to public and someone trying to access this API will need specific rights or licenses
3. Internal API: It is also known as Private API as only internal systems can access this type of API and they are designed for internal use within a company
4. Composite API: It combines different data and service APIs. It is a sequence of tasks which runs synchronously as a result of execution to improve the performance of listeners in the web interfaces

Types of API protocols:

SOAP (Simple Object Access Protocol)

It is a protocol that uses XML as a format to transfer data. It enables users to send and receive data through SMTP and HTTP. With SOAP APIs, it is easier to share information between apps or software components that are running in different environments or written in different languages.

REST (Representational State Transfer)

It is a set of architectural principles unlike other protocols which have a predefined set of standards. For an API to be RESTful, the interface must follow certain architectural constraints.

REST Design Principles: 

There are mainly 5 design principles which every REST API must adhere to:

1. Uniform Interface: All API requests for the same resource should look the same, no matter where the request comes from. The REST API should ensure that the same piece of data, such as the name or email address of a user, belongs to only one uniform resource identifier (URI). Resources shouldn't be too large but contain every piece of information that the client might need.
2.  Client-Server: Client and Server systems should be completely independent of each other. The only information the client application should know is the URI of the requested resource, it can't interact with the server in any other ways. Similarly, a server application shouldn't modify the client application other than passing the requested data via HTTP.
3.  Statelessness: REST APIs are stateless, which means each request needs to include all the information necessary for processing it. REST APIs do not require any server side sessions and Server applications are not allowed to store any data related to a client request.
4.  Cacheability: Resources should be cacheable on the client or server side. Server responses also need to contain information about whether caching is allowed for the delivered response. The goal is to improve performance on the client side, increasing scalability on the server side.
5.  Layered System Architecture: In REST APIs, the calls and responses go through different layers. It should not be assumed that the client and server applications connect directly to each other as many intermediary systems are involved in the communication loop. REST APIs need to be designed in a way such that neither the client nor the server can tell whether it communicates with the end application or an intermediary.

REST API Methods:

• Get - Used to retrieve information about the Rest API resource
• Post - Used to create a new Rest API resource
• Put - Used to update an existing Rest API resource
• Patch - Used to partially update an existing Rest API resource
• Delete - Used to delete an existing Rest API resource

API Authentication Methods:

• Basic Authentication: Client sends the username and password in the request header
• Bearer Authentication: Access is provided to a bearer token. Bearer token is an encrypted string of characters that server generates in response to a login request
• API Keys: Server assigns a unique generated value to a first time client. Whenever the client tries to access resources, it uses the unique key to verify itself
• OAuth: It combines passwords and tokens for highly secure login access to any system. The server first requests a password and then then asks an additional token to complete the authentication process

API Response Status Codes:

• 200 OK: Successful HTTP Requests
• 201 Created:  New resource was created
• 204 No Content: Resource removed and no content was returned
• 404 Not Found: Resource was not found on the server