APIs and Restful APIs

API stands for Application Programming Interface and it can be considered as a contract that is used when two or more separate software systems need to interact together to achieve something they cannot do independently.

API usually contains a set of functions or classes that are exposed for other systems to be used by passing argument. Additionally, it contains a human readable explanation for each exposed component.  An analog example which demonstrates the concept of API is when the client goes in a restaurant.  The client gets a menu and he/she can order only the items listed in the menu. After the client makes the order, he/she does not have the right to go inside the kitchen and check what the cooker is doing or how the food is being prepared. In this example, you can think of the menu as the API .

There are different type of APIs. There are APIs for web services, applications and for operating systems. An example of API is YouTube API, which allows other developers to integrate YouTube videos inside other websites or applications. Another example is Google Directions API, for example some of my friends who graduate this year developed an applications which helps tourist explore a new place, they made use of Google directions API. When the user of their application tries to find how to go to a specific restaurant, their application passes the information of that restaurant as an argument to a Google direction function (which is in the Google directions API) and then returns an direction object which can be displayed inside their app.

When talking about APIs, rest structure is a concept related to it. Rest stands for Representational Style Transfer and it is an architecture style used to design web services. Basically, restful APIs are APIs  which have to follow some constrains.

  1. Uniform interface

The standard database CRUD (Create Read Update Delete) is translated into HTTP (Hypertext Transfer Protocol) commands which are Post, Get, Put and Delete.

  1. Stateless

Server does not have a client state, so each request should contain the complete information necessary for the request to be understood from the connector.

  1. Cacheable

The response should be cacheable which means that the client cache is given the right to reuse that response data for later equivalent requests.

  1. Client-Server

The client makes a request to the server through HTTP protocol, server processes the request and returns an response or gives an error. The client accepts the response and gets the information it needs from the response.  Separation from the concern is the basic idea behind client server constrain. The separation of functionalities of the server and the client simplifies the relation and improves scalability.

  1. Layered System

System should be composed of hierarchical layers; Client cannot be connected directly to the server but intermediate layers such as other software or hardware components should be in between. This constrain contributes on simplifying the overall system complexity, hence contributing on scalability.

  1. Code on demand

This constrain allows client functionality to be extended by downloading and executing code in form of applet or scripts.

As I have mentioned above most restful APIs are based on HTTP, and the CRUD operations are implemented through request methods of HTTP. But what exactly do these operations do?

Below I have provided an explanation of each request method and possible responses for each request.

  • GET – retrieves a resource

Response status:

200 “OK” – general success

400 “Bad Request” – general failure

404 “Not Found” –URL does not map to the source

  • POST – creates a new resource

Response status:

201 “Created” – resource is successfully created

400 “Bad Request” – general failure

  • PUT – updates a resource

Response status:

200 “OK”– general success

404 “Not Found” – URL does not map to the source

400 “Bad Request”– general failure

301 “Moved Permanently” – resource is reallocated

  • DELETE – deletes a resource

Response status:

204 “No content” – deleted successfully

404”Not Found” – URL does not map to the source.

An example of Restful APIs is  Twitter restful API.  To get the latest post, user can provide a query string or an hashtag to the API and it will return the results in JSON format.

Leave a Reply

Your email address will not be published. Required fields are marked *