BEST PRACTICES FOR REST API DESIGN.

6 min readApr 14, 2021

REST APIs are one of the most widely used types of web services today. They use the REST API to connect with a server from a variety of clients, including browser apps.

As a result, it is critical to properly design REST APIs so that we don’t run into issues down the road. For API users, we must consider protection, efficiency, and ease of use. Otherwise, we cause issues for clients who use our APIs, which is inconvenient and discourages people from using them. If we don’t follow widely accepted conventions, we’ll annoy the API’s maintainers and the clients who use them because it’s not what they anticipate.

In this article, we’ll look at how to design REST APIs so that they’re simple to use, future-proof, stable, and fast, especially because they serve data to clients that may be sensitive. Since a networked application can fail in a variety of ways, we should ensure that any REST APIs manage errors gracefully using standard HTTP codes that assist consumers in resolving the issue.

ACCEPT AND RESPOND WITH JSON

REST APIs can accept JSON as a request payload and return JSON as well. JSON is the industry standard for data transfer. It can be used with almost any networked technology: Using the Fetch API or another HTTP client, JavaScript has built-in methods for encoding and decoding JSON. Server-side technologies include libraries that can decode JSON quickly and efficiently.

There are other options for data transfer. Without translating the data to anything that can be used, which is normally JSON, XML isn’t commonly accepted by frameworks. On the client side, particularly in browsers, we can’t manipulate this data as easily. It turns out that simply transferring data is a lot of extra work.

Form data is useful for sending data, especially when sending files. However, we don’t need form data to transfer text and numbers because most frameworks allow us to transfer JSON by simply having the data from it on the client side. It’s by far the simplest way to go about it.

To make sure that when our REST API app responds with JSON that clients interpret it as such, we should set Content-Type in the response header to application/JSON after the request is made. Many server-side app frameworks set the response header automatically. Some HTTP clients look at the Content-Type response header and parse the data according to that format.

Only if we’re trying to send and receive files between client and server is there an exception. After that, we must deal with file responses and send form data from the client to the server. But that’s a discussion for another day.

We should also ensure that the responses from our endpoints are JSON. This is a built-in feature in many server-side frameworks.

Let’s take a look at an example API that accepts JSON payloads. This example will use the Express back-end framework for Node.js. We can use the body-parser middleware to parse the JSON request body, and then we can call the res.json method with the object that we want to return as the JSON response as follows.

bodyParser.json() parses the JSON request body string into a JavaScript object and then assigns it to the req.body object.

USE NOUNS INSTEAD OF VERBS IN ENDPOINT PATHS.

Endpoint paths do not include verbs. Instead, as the pathname, we can use nouns that reflect the entity that the endpoint that we’re retrieving or manipulating.

This is because the verb is already present in our HTTP request form. Verbs in API endpoint paths aren’t useful, and they make the path unnecessarily long because they don’t convey any new information. The developer’s choice of verbs could change at any time. For example, some people prefer ‘get’ while others prefer ‘retrieve,’ so it’s best to let the HTTP GET verb tell us what an endpoint does.

The HTTP request method we’re using should show the action we’re taking. GET, POST, PUT, and DELETE are the most popular methods. GET retrieves resources. POST submits new data to the server. PUT updates existing data. DELETE removes data. The verbs map to the CRUD operations.

With the two principles we discussed above in mind, we should create routes like GET /articles/ for getting news articles. Likewise, POST /articles/ is for adding a new articles, PUT /articles/ :id is for updating the article with the given id . DELETE /articles/ :id is for updating the article with the given id . DELETE /articles/:id is for deleting an existing article with the given ID. /articles represents a REST API resource. For instance, we can use Express to add the following endpoints for manipulate articles as follows:

We specified the endpoints to manipulate articles in the code above. As can be seen, there are no verbs in the route names. We only have nouns. The verbs are included inside the HTTP verbs.

The GET endpoint, like the POST, PUT, and DELETE endpoints, accepts JSON as the request body and returns JSON as the answer.

NAME COLLECTIONS WITH PLURAL NOUNS.

Plural nouns can be used to name collections. Since we rarely want to purchase a single object, we should be consistent in our naming and use plural nouns.

To be compatible with our databases, we use plurals. Tables usually have several entries and are called to represent this, so we can use the same language as the table the API accesses to be consistent.

With the /articles endpoint, we have the plural form for all endpoints, so we don’t have to change it to be plural.

MAINTAIN GOOD SECURITY PRACTICES.

Since we often send and receive private information, most client-server contact should be private. As a result, SSL/TLS is required for protection.

It’s not difficult to install an SSL certificate on a server, and the cost is either free or very low. There’s no reason why our REST APIs shouldn’t communicate over secure channels rather than in the open.

People shouldn’t be able to get any more details than what they asked for. A regular user, for example, should not be able to access the details of another user. They shouldn’t have access to administrators’ data either.

We need to incorporate role checks for a single role or provide more granular roles for each user to enforce the concept of least privilege.

If we want to divide users into a few roles, the roles should only have the permissions that they need. If each function that users have access to has more granular permissions, we must ensure that admins can add and remove certain features from each user as required. We also need to incorporate some pre-defined functions that can be assigned to a group of users so we don’t have to do it manually for each user.

CONCLUSION

The most important thing to remember when developing high-quality REST APIs is to stick to web standards and conventions. The modern web’s standard building blocks include JSON, SSL/TLS, and HTTP status codes.

Performance is also a significant factor to consider. We will improve it by not returning a large amount of data all at once. We can also use caching to avoid having to check for data all of the time.

Endpoint paths should be consistent; we only use nouns because HTTP methods specify the action we want to take. Nested resource paths should be placed after the parent resource’s route. They should tell us exactly what we’re receiving or manipulating so we don’t have to read additional documents to figure out what’s going on.