REST API Best Practices – Comprehensive Handbook

Quick Overview:

This blog post is a handbook that sheds light on the REST (Representational State Transfer) architecture. We have covered what are the key aspects to look-into the best API designs, what are the 6 architectural constraints of REST API, and shared our archived top 12 REST API Best Practices 2021 that help you build robust enterprise applications architecture.

Table of Contents

Introduction

Sure, you might be thinking that the REST API has given no standards or rulebook to follow when designing your representational state transfer app interface. However, we at Bacancy Technology have identified and are practicing these 12 best practices for REST API design.

The RESTful system is often restricted by a uniform interface, code on demand, client-server architecture, cacheability, client-server architecture, or statelessness. But this does not limit the designers because REST is merely a design approach and not a standard or framework.

Since the genesis of the restapi approach as found by Roy Fielding in the year 2000 and over these 20 years of software development, we have adapted these REST API best practices design in 2021. We hope they will turn up to be helpful to you too.

What is REST API?

Let us begin from dawn. For those who want to get the very idea of the Restful application programming interface, we’re here with the definition:

“REST stands for Representational State Transfer, and it is an application programming interface. The HTTPs communication protocol mostly accesses it”.

3 Best Traits of REST API Architecture Design

1. Easy to Work with, Easy to View:

A well-grounded API will be uncomplicated to work with. Its resources and other related operations should be quickly committed to memory by developers who deal with it consistently. Thus, an ideal API should be trouble-free to read and write so that designers and developers are comfortable working with it.

2. Tough to misuse:

Integration with an API having a good design will be quite straightforward when writing inaccurate code becomes less likely to occur. It has knowledgeable feedback and does not enforce any severe guidelines on the API end customer.

3. Outright & concise:

With conciseness, we mean that a comprehensive API will enable developers to create full-fledged applications in opposition to your exposed data. Usually, completeness takes place over time, and maximum API designers gradually build on top of the existing APIs. Thus, this is an ideal trait of the best API design that every organization or an engineer having an API should be dedicated to.

6 Constraints of REST API Design Architecture

1. Uniform interface

By REST, you use the same concept to decouple the client from implementing the REST service. Compare interface with a contract signed between client-server where you must use certain standards. The reason being, globally accepted APIs should enforce global concepts, like standards, to make them understandable.

2. Stateless

Having gained inspiration from HTTP, Roy fielding considers this constraint. By this architectural constraint, we mean to make all the client-server engagements stateless. This way, the server will not reserve anything regarding the latest HTTP request made by the client. Hence, it will consider every request as a new and unique one. Moreover, it must not rely on any prior information exchanged between the two. This further means no session, no history.

The client is held accountable for handling the application’s state. A client application requires a stateful application for the end-user, wherein the logs in once and carries out various authorized operations. Every request from the client must involve all the essential information for servicing the request and authorization details and authentication.

3. Client-server

Here, we mean that the server application and the client application should evolve individually without the need to depend on each other. To be more precise, it should stick to the separation of concerns. By separation of concerns, the code on the client end can be modified/altered anytime without creating any impact on the conditions of the server. Additionally, the code on the server end can be altered without altering the conditions of the client.

By maintaining the separation of concerns, we can enhance the flexibility and Scalability of the particular interface across various platforms. A client must be aware of resource URIs only. Unless and until the interface between clients and servers is kept unaltered, they can be developed and replaced separately.

4. Layered system

Generally, components are unable to view beyond the immediate layer. REST enables you to make use of a layered architecture system. Here, you can deploy the APIs on server A, save data on server B, and verify requests on server C. These servers may offer a security layer, a load-balancing layer, a caching layer, and several other functionalities. Additionally, any of these layers must not influence the responses or requests.

5. Cacheable

Today, caching holds vital importance wherever applicable. With caching comes an enhanced performance for the client, leading to an improved scope for scalability for a server with a reduced load.

When it comes to REST, every response can be termed as cacheable and non-cacheable. You can use the cached response as the request-response instead of checking with the server. This helps in eliminating the interaction required between the client and the server up to some extent.

6. Code on demand (optional)

This one is generally an optional constraint. Usually, you will be required to send a static representation of resources in a JSON REST API or XML form. However, whenever you need to, you can easily return executable code for supporting a vital part of your application.

REST API Best Practices

Below are the 12 assembled REST API Best Practices design that we implement and have helped us in our business applications. Check them out if they might help you as well.

1. Use Nouns and not Verbs in URI

REST APIs must be developed for resources that can be services, entities, etc. Hence, they should always consist of nouns and not verbs. This means that we must refrain from using verbs in REST endpoint paths. Instead, we must implement nouns that represent a certain entity.

Why? Because the HTTP request method that we use already consists of a verb. Having verbs in the REST API endpoint path does nothing and, thus, is unnecessary as it does not fetch any new information.

The selected verbs can vary from a developer’s notion. For example, some prefer ‘get’, while some prefer ‘retrieve’. Hence, it is better to allow the HTTP GET verb to state what an endpoint does.

The action must be specified by the HTTP request method made by us. Generally, some basic methods involve

• GET, PUT, DELETE, and POST.
• GET rectifies and recovers resources
• PUT updates the current data
• DELETE eliminates data
• POST delivers new and unique data to the server.

The verbs map to Create, Read, Update, and Delete(CRUD) operations. Hence, to get news articles, you have to create GET /articles/. POST /articles/ to add a new article, PUT /articles/:id for updating the article provided by the given ID, and DELETE /articles/:id to delete an article provided by the given ID. /articles denote a REST API example resource.

For example, we can employ Express to implement these endpoints to manipulate articles like,

In the code above, you can see that the path names do not consist of any verbs in them. It states all nouns and HTTP verbs.

2. Use Plural naming conventions

Usually, we prefer using plurals. However, know that no rule states one cannot use a singular when it comes to the resource name.

Here’s why plurals are used:
We are working on one resource from the set of resources. Hence, to illustrate collection, we make use of plural naming conventions.

For example, let us consider GET /users/123. The client here asks to rectify and recover a resource from the user’s collection with ID 123. While developing a resource, if we need/wish to add another resource to the existing collection of resources, the API looks like POST /users.

3. Hypermedia as the engine of application state (HATEOAS)

This constraint stands out for several other network application architectures from the REST architecture. The Hypermedia As Transfer Engine Of Application offers easy navigation via certain resources and their available actions. By this, a client is not required to know how to communicate with an application for distinct actions because each of the metadata gets embedded in the responses sent from the server.

For a clearer understanding, let us look at an example. Here is a response of a retrieved user having ID 123 from the server.

At times, it is easy and comfortable in skipping the format of links, thereby specifying links as fields of a resource given below:

Ideally, it is not a convention that needs to be followed every time. This is because it relies on resource size/fields and actions that can be executed on resources. If resources consist of multiple fields that users do not wish to go through, it is better to show navigation to sub-resources followed by implementing HATEOAS.

4. Swagger

Swagger is a popular and widely used tool that is used to document REST APIs. It offers a way to analyze the use of a particular API, thereby enabling developers to be aware of the fundamental Semantic behavior. To be more precise, it is an analytical way of incorporating documentation using annotations that further gives rise to a JSON that describes APIs and their usage.

5. Use only JSON

REST enables using various output formats such as JSON, RSS, XML, CSV, and HTML. Although, this entirely depends on what you require your API for and the application you possess. If you have a public-facing service that you wish to be available via REST API design, you must choose JSON data format. Almost in 99% of cases, JSON is the most preferred data format for interacting between payload and response.

To ensure when the REST API design app responds with JSON, you must set Content-Type in the header in response to the application/JSON following the request. Various server-side app frameworks automatically set the response header. Few HTTP clients see the Content-Type response header and review the data as per the format.

One and the only exception is at times when you try to exchange files between server and client. For this, you are required to manage file resolves and send form data directly from the client to the server. However, that is a different topic. All and all, keep in mind that you need to ensure that your endpoints return JSON REST API as a response. Several server-side frameworks own this built-in feature.

6. Allow filtering, sorting, and pagination

Few key features for consuming API include filtering, sorting, and paging. Often, resource collection can be huge. The databases behind REST API standards can also get enormous. Eventually, it brings down the performance of our systems. To eradicate these, we can use,

• Filtering: To shrink the query results by certain parameters. For example, country or creation date.
• Sorting: This enables sorting the results in an ascending or descending order by a selected parameter/(s). For example, by date.
• Paging: It uses ‘limit’ to narrow down the count of results displayed to a certain number and ‘offset’ to denote the part of the result range to be displayed. This is significant in cases where the count of total outcomes is greater than the ones introduced.

By pagination data, we ensure returning only a couple of results instead of collecting all the requested data at once. By filtering and pagination, you can elevate the performance as there is a potential reduction in the usage of server resources. With more and more data assembling in the databases, these features become more important.

7. Performance optimization with Caching

You can add caching to bring back data from the local memory cache rather than querying the database for obtaining the data every time you wish to retrieve any data requested by the users. An excellent point of caching is that users can achieve data even faster. However, many times, the data achieved by users might be outdated. Eventually, this can lead to major problems while debugging in production environments, as anything might go wrong because users entertain old data.

There are several types of caching solutions, such as in-memory caching, Redis, etc. With this, you can alter the way data is cached as your requirements change.

For example, Express possesses the api cache middleware to add cache to the app without considerable configuration. You can incorporate an easy in-memory cache to our server such as,

In case you use caching, ensure including Cache-Control information in headers. This will assist your users efficiently in using your caching system.

8. Error Handling

To cut off confusion for all API users, errors must be handled gracefully, thereby returning the HTTP response codes that denote the nature of the error that has occurred. This provides the API maintainers sufficient information to analyze the source and cause of the problem. In case you don’t wish errors to harm your system, you can leave them unhandled. This means that the API consumer has to handle errors.

Here is a list of common error HTTP status codes. Let’s have a look!

• 400 Bad Requests: This denotes that the client-side input has failed documentation/validation.
• 401 Unauthorized: This denotes that the user is unauthorized for accessing a resource. Usually, it returns when a user is not verified.
• 403 Forbidden: This denotes that the user is inappropriate and is not allowed to access a resource even after being verified.
• 404 Not Found: This denotes that no resources are found.
• 500 Internal server error: This is a common server error.
• 502 Bad Gateway: This error marks an invalid/null response from an upstream server.
• 503 Service Unavailable: This denotes that something unpredicted and unusual activity took place on the server-side. (server overload, part failure, system failure)

Error codes are required to accompany messages with them so that the API maintainers can obtain sufficient information for troubleshooting the issue. However, attackers cannot utilize the error content for cyberattacks, such as bringing the system down or stealing vital information. If your API stays incomplete, you should send errors along with information to allow users to take corrective actions.

9. Versioning

Never skip versioning your API. Versioning enables you to repeat faster, thereby preventing inapplicable requests to hit updated endpoints. Alongside, it assists in smoothing over any complex API version transitions as you can keep offering old API versions for an extended period.

Generally, there are mixed reviews regarding whether an API version must be incorporated in a header or the URL. Well, if we speak academically, it must be situated in the header. However, the version requires to be present in the REST API URL, thereby ensuring the exploration of the browser across several versions, enjoying an easy and simple developer experience.

Ideally, an API can never be stable. Hence, it is a variable. Although the change is unavoidable, what is important is to look at how to manage the change. An excellent practice for plenty of APIs is well-documented and announced depreciation schedules every month.

Few examples of endpoint URI versioning include:

• https://api.stripe.com/v1/ (major version indication only)
• https://us6.api.mailchimp.com/3.0/ (major + minor version indication)
• https://api.twilio.com/2010-04-01/ (date based indication)
• https://developer.github.com/v3/ (major version indication only)

10. Resource hierarchy

If a resource consists of sub-resources, ensure depicting this in the API, thereby making it clear and specific. For instance, if a user has posts and we wish to retrieve/ redeem a certain post by the user, API can be interpreted as GET /users/123/posts/1. This will retrieve the post having id one by the user having the id 123.

Many times, resource objects can be linked with one another or possess some sort of functional hierarchy. It is usually a better idea to restrict the nesting to a single level in the REST API. If you think of implementing too many nested levels, it might not look elegant. Also, by filtering, you can achieve a similar result.

11. Idempotence (Misusing Safe methods)

Some safe methods are HTTP methods that return the exact resource representation. GET, TRACE, OPTIONS, and HEAD methods are referred to as safe. By safe, we mean that they are ideally expected to retrieve data without changing the state of a resource on the server.

Moreover, refrain from using GET to delete content, like GET /users/123/delete.

Generally, it is nothing like it cannot be executed, but the problem arises because the HTTP specification gets violated in this case. Hence, make use of HTTP methods as per the action that you are required to carry out.

12. API Documentation

Publishing your API documentation is extremely vital. Not only do these help developers, but users as well. When you publish the API documentation, developers view what they are dealing with while making an implementation. Besides this, publishing enables potential users to look into what is made available through your API.

API Documentation must offer information regarding the existing methods and endpoints, potential response codes, request/response examples, existing throttling or limits, and information about authorization. An excellent idea for this is to publish the documentation in a browsable web page format that has engaging options, playground, and curl examples.

Bear in mind that the API documentation even represents your organization. A comprehensive, well-written, and exceptionally presented document will be acknowledged by the developers and partners, thereby creating an example of how it must be created. However, if a clumsy and poorly designed documentation that has no examples has plenty of errors and is outdated, it may eventually harm the image of your organization.

Some excellent examples of API documentation are,

• Mailchimp
• Twilio
• Stripe

Conclusion