As time passes and you are doing services that have to be scaled and integrated with other services, you are realizing how necessary is a good design or at least a minimally well thought and executed design that meets a series of minimum requirements.

The underlying concept of a RESTful API is to divide the structure of the API into logical resources, mounted on a URL, that allows us to access information or concrete data using HTTP methods such as POST, GET, PUT and DELETE to operate with resources. These methods are comparable to the CRUD operations (Create, Read, Update, Delete) of the databases. Clarified this, let’s start with the recommendations.

Use names but not verbs

For reasons of better understanding and readability of API semantics, use only names for its entire structure. The semantics that makes up the URL, together with the HTTP method used (POST, GET, PUT, DELETE), allows to dispense with verbs such as “create”, “get”, “update” and “delete”.

GET methods and query parameters should not alter the state

Use the POST, PUT or DELETE methods to change the states of the resources, instead of using the GET method or a request with query parameters. For something you have 3 methods that allow you to do that. Which one to use depends on the design of the database or the logic with which the storage of the same is structured.

Use plural names

Do not mix singular names with plural names. Make it simple and keep the names in the plural.

Use HTTP headers for serialization of formats

Both the client part and the server part need to know in what format the data is being passed in order to communicate. The simplest thing is to specify it in the HTTP header.


The use of HATEOAS (Hypermedia as the Engine of Application State) is a design that allows us to include the principle of hyperlinks in a similar way to web browsing, which allows us better navigation through the API. This type of design is designed for the longevity of software and independent evolution, since frequently in the architecture of systems and services, it is in the short term what most often fails.

Provide filtering, sorting, field selection and paging for collections

Use a single query parameter for all fields or a formalized query language to filter.Allow ascending or descending order over several fields. Allow the selection of a few fields of a resource if not all are required. Give the API consumer the possibility of which fields he wants to return, reduce the volume of traffic in the communication and increase the speed of use of the API.

These are just basics regarding design and API. If you want to learn more, visit stoplight.