API is one of the primary requirements for any application. People want to expose data to the external world ensuring all the data to be consumed easily and quickly. With the proliferation of AI and Machine learning, the data created over time becomes more relevant and important to many other vendors. As an integration platform, our main focus is also on how to consume these important data points to get meaningful insights. Just like all other integration platforms, our platform also supports a number of standard protocols which can easily connect to various APIs without writing a single line of code. REST is also supported in-built on the platform to ensure any third-party applications supporting REST-based communication protocol can be easily connected.
To comply with standards for an API, software vendors build REST-based APIs to easily connect to a wide variety of software tools available online. Some of the free tools like Swagger, PostMan, Rest-Assured, RESTClient, etc. allow developers or API consumers to quickly and easily test a REST API without writing a single line of code. To comply with the usage of these APIs, one must ensure the standards are followed and the Request / Response structure provides meaningful insights.
- Introduction
- Why REST?
- Various Elements of REST API
- Navigation
- Methods
- Headers
- Eventing
- Error Codes
- Authentication
- Bulk APIs
- Some Best Practices
- Conclusion
Introduction
REST stands for Representational State Transfer. Web application generating data over time requires an endpoint that could easily be consumed in real-time by a different set of applications such that the data generated by these applications can be made meaningful to other applications. The integration allows the users to generate services that allow seamless interaction between different sets of applications to and fro. REST ensures a standard mechanism to ensure a smooth transfer of data without affecting or minimally affecting the applications.
Do you have multiple systems running? Connect all your business applications under one single platform to automate the business process and increase your productivity and efficiency via the best-in-class API-led connectivity!
Why REST?
REST provides a standard protocol to make data transfer between applications easy and effective. Think of traditional web services, where you expose interfaces as methods. Clients who are consuming them requires to know the method names which you intend to provide. For this reason, documentation of APIs was of utmost importance. SOAP APIs are unnecessarily complex and require an in-depth understanding of WSDL (a completely new language) to understand the request and response structure. These APIs are not readable and function-oriented. But as per the present age, where objects and classes are in place, why do we still go on using the traditional approach. REST exposes objects as per their data. For instance, to get Customers, Action GET is used as a method and the object Customer is used in the URL. This makes the APIs so much simple to understand and uses all the features which HTTP 1.1 protocol provides. REST is very easily understandable and does not require any special knowledge to understand a language.
In addition to that, REST is also preferred because of the large number of tooling available on the market which easily consumes a REST API. As REST is one of the standard ways of communicating data, any application can easily consume it.
Various Elements of REST API
As REST is a standard, there are already standard protocols defined for it to execute. There are various components of a REST API which one needs to follow while building an API. Let us discuss some of the existing elements of a REST API which one needs to follow while developing an API.
Navigation
Documentation of a REST API is the core of any API. It is important to understand that every data exposed to a REST API should be self-explanatory and any developer who is consuming it can use one similar knowledgebase to understand and update API. Let us take an example of how APIs are designed.
https://restclient.appseconnectapi.com/Customers
https://restclient.appseconnectapi.com/Customers?filter=department[eq]sales&limit=20&offset=40
https://restclient.appseconnectapi.com/customer/10/details
REST API is not new to the world. Standard API connectivity relies heavily on the REST protocol as it is widely accepted and easily adapted. Here’s how you can Embrace REST APIs through APPSeCONNECT!
If you look at the first 3 URLs, you can easily understand how the different types of REST navigation URL expose. The first URL provides a list of Customers. You can use similar knowledge to list products, organizations, comments or any data. You just need to replace the noun in the URL here, which is Customer.
The second URL provides additional information like filter structure, paging, etc. Paging is maintained using limit and offsets query string properties. The filter is also maintained using the standard filter query string key. The same structure works just similar to the other objects.
The third URL retrieves detailed information about a particular customer. Check the URL is not pluralized here and the id is replaced as a part of the URL. The value 10 represents the id of the customer for which all the details are returned.
Embracing statelessness in the core of an API is of utmost importance. The web is stateless as we all know, but how does API provide the same feeling to the consumer? With REST, navigation provides a complete flow of data and every URL that exposes a set of information does not provide any state information.
Methods
While navigation represents the endpoints, the methods represent the actions. For each URL, it is important to understand what kind of action the user wants to perform. For instance, in all the above URLs, the user only wants to get data from the server. In such cases, the method will always be GET. Here is the list of all methods supported for any REST API.
GET – This is an HTTP method used to get data from the server.
POST – This is used to send or push data to the server. Hence, if the user needs to update data on the server, it is POST that is required.
PUT – This is to update existing information in the server.
DELETE – As the action suggests, this method will allow deleting an existing data from the server.
These are the main methods that a REST API used for CRUD operations. There are a few other methods too, which one can use to infer special operations. Some of the methods like :
HEAD – Returns the header information about a resource. It is used to identify what formats are accepted for a particular API resource.
PATCH – This is used to partially update data. In the case of PUT, the whole data is updated whereas, in PATCH, only the properties that are passed were updated.
OPTIONS – They do not have any side effects, and this will return which HTTP methods are available for the resource. For instance, if only GET and POST methods can be applied, the Allow header will return these.
TRACE – TRACE is used for diagnostics purposes.
The methods GET, HEAD, PUT And delete is regarded as idempotent methods as these operations will produce the same result if they are called multiple times.
Headers
Just like methods, REST also uses headers extensively to ensure all the information about a resource is returned as a response. For instance, the Content-length returns the number of characters that are returned by the API to the user such that they can have a check on the actual length of the body before downloading the content. The headers of a REST API represent the metadata information associated with an API or a resource.
The headers of a REST resource is divided into Request and Response headers, where Request is the metadata that is sent to the server for a resource and response is the data generated by the server as a response.
Request Headers
Accept: Specifies the content types that are valid as a response to the requester. If the server cannot respond, it will return a 406 Not acceptable status code.
Content-Type: Specifies the content type or the format of the body element.
If-Match: This header will indicate the entity version before updating it to the server. The entity version is sent as ETag.
If-None-Match: This header is used to check whether the server has modified a particular resource. If ETag is not matched, the server responds with the new update or it returns 304 – Not modified.
Response Headers
Allow: Lists the allowed HTTP Methods for a particular request.
Content-Type: Represents the type of content returned as a response.
ETag: An alphanumeric string representing the version of a resource.
Status: HTTP status code.
In addition to them, there are a number of other important headers, which are used in special scenarios.
Eventing
There are two types of APIs available.
- Polling
- Webhooks
Generally, API means the Polling API where the updates are only retrieved when the consumer initiates a new request. All the APIs discussed here are polling APIs. But in some scenarios, when we truly require API to be real-time, we take a different approach where the API is configured with a callback URL, which is automatically triggered when an update event occurs on the server.
In this diagram, it is depicted that the polling requires a request to be triggered to return a response. In the case of Webhooks, the callback URL is already configured and the consumer receives the callback when an update occurs on the server from time to time.
Error Codes
As any standard API requires an active solution to errors, the REST standard also provides such support. Here is the list of all error codes that are more prominent and usually returned when there is an exception on the server.
1XX – Informational
100 – Continue
101 – Switching protocol
102 – Processing
103 – Early hints
2XX – Success
200 – OK
201 – Created (For Post operation)
202 – Accepted
204 – No Content
206 – Partial Content
3XX – Redirection
301 – Moved Permanently
302 – Found
304 – Not modified
308 – Permanent Redirect
4XX – Client Error
400 – Bad request
401 – Unauthorized
403 – Forbidden
404 – Not Found
405 – Method not allowed
406 – Not Acceptable
429 – Too many requests (Used to indicate server throttling)
5XX – Server Error
500 – Server error
501 – Not implemented
502 – Bad gateway
503 – Service unavailable
Authentication
Similar to every area of REST, Authentication is also standardized. Authentication represents the accessibility for a particular resource such that only the right person having the right permission can access a resource. Authentication at its core has the ability to identify the caller such that it can log a request client id from the server for auditing. There are a number of authentication mechanisms, some being very simple, while some are extensive with multiple request-response structures involved. Some of the widely known authentication mechanisms are :
Basic
HTTP basic authentication is the most straightforward method and the easiest. With this method, the sender places username: password in the request header. The basic authentication directly parses the base64 string-based user id and password combination to authenticate every request. This method does not rely on any security headers like cookies, session ids, etc, and also does not maintain any state for the customer login.
Example, Authorization: Basic bfYl39syZQGVOn==
Bearer
Bearer type of authentication uses a bearer token that is passed to a customer to call a resource. The bearer token is a security token generated by the user and used for every call he makes on the server. A bearer token is generated behind a valid login by the user.
OAuth
Open authentication is currently the most secure authentication mechanism that requires the user to generate a token by logging in using the user id and password and then reusing the refresh token for every session failure. This type of authentication allows establishing scopes that provide different parts of an API server and hence can easily revoke permission to a resource after a certain timespan.
Bulk APIs
In the case of applications requiring bulk operation or sending out bulk data to and from a source, bulk API comes very handy. REST supports bulk APIs which can be used to programmatically send out a large number of transaction requests to the server. As the web is stateless, it has latency when calling the same API multiple times. Think about a scenario where you want to update 100 records at a time. In the case of normal API, you might need to do 100 connections, then call the API and then disconnect. This additional connecting and disconnecting requires a lot of time for the consumer.
Using the Bulk APIs, one can easily send all the data at a time and the server returns 202 – Accepted status. The server in turn uses a batch processing job to do the operation on each of the data passed.
Best practices of developing REST APIs
Now as you already know the basics of REST API, let us consider developing some of the best practices that one should follow while developing a REST API. Here are some of the points :
- Avoid using Verbs in URLs. – When defining a restful service, avoid using verbs for the resource inside the URL such that we don’t confuse the operation with a resource. Generally, the HTTP method is sufficient to do such a thing.
# Don’t
POST: /articles/createNewBlog/
# Do
POST: /articles/ - Always use the plural form of noun such that all URLs are consistent. You could use a singular form to get a particular resource, but in such a case the base URL will be invalid.
GET: /blogs/2/
POST: /blogs/ - Avoid returning plain text. Even though REST supports returning plain text, but it is not recommended approach. One should always return data using a valid format such that tools can easily parse the texts. JSON or XML is the standard way of defining a response.
- Return error details in Body. Even though in most cases, errors can be identified by the status code, but the details are sometimes necessary. To define error messages, you must return the data in the body such that any structure of data could be managed.
- Use Status codes consistently. Status codes are something that returns the response status of a resource. If you are using 201-created for one POST operation, you should always use the same for every resource creation.
- Make use of query strings for Pagination and Filtering. All the filtering criteria for REST should use filtering through query string such that one can bookmark the link on the web browser. RESTful APIs are stateless, and hence it is easy to identify the state information if the query string of the URL refers to it.
Conclusion
As you understood all the basic information about REST, it is important to consider how these are consumed. I see a large number of badly behaving REST APIs in the market which still works but is not much representable. Designing a good REST API requires a lot of architectural work to plan and execute a plan. Even though writing a REST API from scratch is sometimes useful, it is also a good idea to take the help of some of the popular platforms present in the market which could help in developing rock solid REST APIs. I hope this topic becomes helpful to all of you. Thank you for reading.
Do you have multiple systems running? Connect all your business applications under one single platform to automate the business process and increase your productivity and efficiency via the best-in-class API-led connectivity!
APPSeCONNECT is a smart and robust business application integration platform that seamlessly connects all your business applications with each other via its best-in-class API-led connectivity, to streamline operations and facilitate the free flow of data across the platforms. By moving into the region of iPaaS, APPSeCONNECT proves to be a best-in-the-class platform that easily connects systems and automates the business process.
