Modern REST API design principles and rules

Typically, when updating or developing an API like Newsdata.io which is a news API for a service to provide news data with quick response time, there are lengthy discussions about the API’s structure, naming, and functions. Although, over time, certain rules have emerged that can be applied to the process and aid in reaching a common ground while developing.

Let’s get started with some basics

What is an API?

API is an abbreviation for Application Programming Interface. It is a software interface that allows two applications to communicate with one another without the need for user intervention.

APIs enable a product or service to communicate with other products and services without requiring knowledge of how they are implemented.

It facilitates communication between the provider and the client. It is a type of software interface that provides a service to other programs. An API specification is a document or standard that describes how to build or use such a connection or interface.

An API is said to be implemented or exposed by a computer system that meets this standard. API can refer to either the specification or the implementation.

What is REST?

REST was created to work specifically with components such as media components, files, or even objects on a specific hardware device. A RestFul web service is any web service that adheres to the REST principles. For working with the required components, a Restful service would use the standard HTTP verbs GET, POST, PUT, and DELETE. REST is an acronym that stands for Representational State Transfer.

GET — requests a representation of the specified resource. Requests using GET should only retrieve data.
POST — submits data to the specified resource.
PUT — replaces all current representations of the target resource with the request data.
DELETE — deletes the specified resource.
PATCH — applies partial modifications to a resource.

When to use REST?

When designing web services, one of the most contentious issues is whether REST or SOAP should be used. In the following situations, REST services should be used:

Limited resources and bandwidth — Because SOAP messages are heavier in content and consume far more bandwidth, REST should be used when network bandwidth is limited.
Statelessness — If there is no need to keep information in a consistent state from one request to the next, REST should be used. If you need a proper information flow, where some information from one request needs to flow into another, SOAP is a better choice. We can use any online shopping site as an example. Typically, these sites require the user to first add items that must be purchased to a cart. To complete the purchase, all of the cart items are transferred to the payment page. This is an example of an application that would benefit from the state feature. The cart items’ state must be transferred to the payment page for further processing.
Caching — If a large number of requests must be cached, REST is the ideal solution. Clients may request the same resource multiple times at times. This may result in an increase in the number of requests sent to the server. The most frequently used query results can be saved in an intermediate location by implementing a cache. As a result, whenever a client requests a resource, it will first check the cache. If the resources are available, the process will not proceed to the server. As a result, caching can aid in reducing the number of trips to the web server.
Ease of coding — Coding REST Services and then implementing them is far easier than SOAP. So, if you need a quick win solution for web services, REST is the way to go.

REST is the most common API architecture in today’s world (representational state transfer). When using REST, you must adhere to JSON rules and format your requests in invalid JSON. Aside from that, a good API should adhere to the following guidelines:

APIs must be separated from the backend, data storage, client, and so on. Because of security and flexibility, it must be a separate layer.

State less — different requests should have no knowledge of one another and be processed independently. That also means that each request must include all of the information required for processing.

API should function in the same way regardless of whether a client sends a request (e.g. is it a web-server or load-balancer or any other client).

REST APIs typically send static resources, but responses can also contain executable code in rare cases (such as Java applets). In these cases, the code should only be executed when needed.

Cacheability — Resources should be cacheable on the client or server-side whenever possible. The goal is to improve client-side performance while increasing server-side scalability. However, there are special headers such as Cache-Control that can be used to control the cache behavior.

Handle errors and return the appropriate error codes. Instead of throwing an internal error to the user, handle it and send the corresponding code and message (e.g. 404 — not found.)

Remember that API should be idempotent (that means that can be invoked many times with the same result). Users can sometimes send duplicate requests to the API. These duplicate requests may have been made inadvertently (or intentionally due to timeout or network issues). As a result, APIs must be fault-tolerant in order for duplicate requests to yield the same results (only POST request is not idempotent).

To create documentation for your API, use swagger or another tool. Documentation is a critical component (if someone going to use that API someday)

There are also some good manners in naming endpoints as well:

Endpoints should be named with nouns that specify the contents of the resource rather than adding a verb for the function that is being performed (e.g., name endpoint /users and use different HTTP methods for working with the user’s entity rather than creating several endpoints like /get-user, /add-user, etc.).
Use clear names: The name of the endpoint should be clear and intuitive (do not use any shortcuts or abbreviations unless they are obvious — /ids are understandable and preferable to /identification numbers).
Forward slashes are used to create a hierarchy by grouping endpoints into logical groups (/departments/ids and /departments/managers are preferable to /departments-ids and /departments-managers).
Use only lowercase letters: Because URIs are case-sensitive (according to the specification), it is best to avoid using upper case unless absolutely necessary.
Separate words with “-”: different words in the endpoint name are usually separated by “-” rather than underscores or camel case.
Avoid special characters: URLs can only be sent and received using the ASCII character set, so it is possible to use only characters from that set (also there are some expectable but unsafe characters like “ percent ”,”[]”,”{}”,”|”,” “,”<>” and it is better to try to avoid using them as well).

The majority of REST APIs are built in conjunction with microservice architecture. In that case, an API structure like this will allow you to change the underlying logic, add or remove components, and so on without changing the communication protocol with other services.

What are the challenges in REST API?

Lack of Security — Unlike SOAP, REST does not impose any type of security. This is why REST is ideal for publicly accessible URLs, but when it comes to passing confidential data between the client and the server, REST is the worst mechanism to use for web services.
Lack of state — Most web applications necessitate the use of a stateful mechanism. For example, if you had a purchasing site with a shopping cart mechanism, it is necessary to know the number of items in the shopping cart before the actual purchase is made. Unfortunately, the client bears the burden of maintaining this state, which makes the client application heavier and more difficult to maintain.