What is API, and why do we hear it often?

Application Programming Interface or API is fundamentally an intermediary allowing two applications to converse with one another. It could be considered as a mediator that shuttles back and forth delivering requests between you and the provider from whom you are requesting. An application programming interface can be considered as a small window that can provide limited access to any software program. This is because it enables other programs to access certain parts of it even when the developer of the program does not provide the entire code.

One real-life example of an API would be any ticket-booking application. While some might prefer using the actual website of the service for booking tickets, most of the users tend to use of external ticket-booking applications to avail the same service. Here, these applications can be considered as APIs as they act as an interface between the user and the actual website.

What is REST?

When creating APIs, there are a few sets of rules and guidelines to be followed to get the best API. This is where Representational State Transfer, most commonly known as REST, comes into play. APIs that follow the REST architectural style are called RESTful APIs. RESTful APIs are designed to exploit existing protocols.

Six main architectural constraints, that are defined by REST, following which one can make a true RESTful API, are:

1. Uniform Interface:

Each resource in the system must be mapped to a unique logical URI. Using this the API consumers are exposed to a limited amount of data. One must make sure that each resource is not too large and contains more information than it is supposed to represent. Also, every resource that has been defined should be accessible by means of a common way, for example HTTP GET.

2. Client-Server

This constraint states that the server application and the client application must not be dependent on each other so that they will be able to evolve separately. The only thing that a client should know is the resource URI.

3. Stateless

As the name of the constraint suggests each HTTP request made by the client must be treated as new by the server. This means that no history and sessions about the HTTP requests made by the client be stored by the server.

4. Cacheable

Caching of data and HTTP responses are very important when it comes to improving the performance for the client-side. This also provides a better scope for scalability for a server as there is a reduction of load. REST states that caching can be applied to resources whenever it is applicable, and in turn the resources are required to declare themselves cacheable. Caching can be done on either server on client side.

5. Layered System

One property of REST is that APIs can be used to connect applications in a layered manner. Different functionalities such as deploying the APIs, storing the data, and authenticating the requests can be done on different servers.

6. Code on Demand

This is an optional constraint of REST. Usually while sending resources between applications, we will resort to making use of static forms of the resources, such as XML or JSON. But when required, executable code can be also returned in order to support any application or functionality.

Prescribed practices for creating a RESTful API.

• HTTP methods

Two main HTTP methods used by a RESTful API are the POST method and the GET method. The POST method is normally used when dealing with websites that have forms. This is because this method protects the data and does not allow it to be sent in the URL on form submission. On the other hand, when using the GET method data can be sent to the URL. This is the default HTTP method. PUT and DELETE are also two HTTP methods used by RESTful APIs. Here are a few examples of the usage of each method.

1. GET -> To Read
/employee – It returns a List of employees
/employee/123 – This returns a specific employee

2. POST -> To Create
/employee – It creates a new employee
/employee/123 – 405 (Method not allowed)

3. PUT -> To Update
/employee – Bulk update of employees
/employee/123 – It updates a specific employee

4. DELETE
/employee – It deletes all employees
/employee/123 –It deletes a specific employee

• Utilize the right HTTP codes

Having proper knowledge about the various HTTP codes and their usage is very important. There are many codes available, each pertaining to a specific case. The most commonly seen HTTP code is 404, which means that the resource was not found. 200 is the code used to specify the condition when a request has taken place successfully. It means OK. In this manner, appropriate HTTP codes must be returned when the APIs encounters any situation.

• Record your endpoints

One important thing to keep in mind while developing APIs is to constantly document, how the endpoints that you are planning to expose are to be used. In this manner it would be easier for other developers, or even yourself later in the future, to be able to proceed.

• Version your API

Like any software, it is always better to improve APIs by developing newer versions and labeling the URL of the API with its corresponding version number. In addition to this, it is highly recommended to keep the new version running alongside the older version so that the users of the old version do not miss out on the features of the new version.

• Use pagination

One of the biggest issues faced while querying large datasets or requesting information from equally large databases is the network traffic that arises due to the large amount of data returned. This can be solved by using pagination. Pagination allows us to set a limit to the number of results that can be returned per page, thus reducing unwanted traffic.

• Keep it Simple

Last, but not the least, it is always better to develop an API which is completely simple in nature. This means keeping the results, alerts, and data formats consistent. In this way, clients will be at ease knowing what to expect. Also, it is a good practice to expose only the required data as a response as opposed to revealing unnecessary data.

Conclusion

Building APIs may seem like an arduous task when it is much simpler than you think. Following the constraints defined by REST and essentially keeping it simple will work wonders and save a lot of time all the while producing the best API yet!