Read
April 1, 2020

API REST Design: 7 essential tips

Ricardo Peloi
Architect Consultant

API REST design in its best version

*updated in March 31, 2020

REST API Design is nothing more than creating an interface with well-defined rules, made available so that you can interact with a system and obtain its information or perform operations.It's like I explained there in the articles about What are APIs: your interface should work like a waiter in a restaurant: getting your orders and returning resources (or dishes), without the customers needing to visit the kitchen to pick up the dish there.

RESTful APIs have gained a huge acceptance worldwide, mainly for following a modern and well-defined standard. However, the design of a RESTful API can suffer from standardization deviations, which in fact happens, many times for lack of a solid knowledge of the concepts.

In this post, we'll know some tips to create an improved and standardized design of what we call a true API in the RESTful standard.

And of course, it's always good to consider that when designing your REST API, you also need to keep in mind who will use it, how it will be used within your strategy, and also how it will be exposed to the world. This reasoning, putting the API in a privileged place in your planning, is called API First.

Use nouns and not verbs

One of the major standardization failures when creating RESTful APIs are related to the pattern of endpoints created (service access URLs). The RESTful standard requires the use of nouns, not verbs or method names. For example:

/getAllCustomers/createNewCustomer/deleteCustomer

These are incorrect forms of nomenclature, which resemble the functions of some object oriented programming language. Instead, for the most appropriate Design, use nouns, such as:

/customers/customers/563

Use HTTP methods correctly

The fundamental principle of REST is to separate your API into logical resources. These resources are manipulated using HTTP requests with GET, POST, PUT and DELETE methods.

For example, when you make a request to the /customers/563 resource using the GET method, you are requesting that a specific client with the code 563 be recovered.

Similarly, when you make the same request (i.e. at the endpoint /customers/536) using the DELETE method, you will be performing a specific client exclusion, code 563.

Use names in the plural

Should the endpoint name be in the singular or plural?

This is a question that usually generates a lot of discussion in RESTful API Design.

In general, it's up to you to choose. In particular, I prefer plural names, since they indicate a set of features (as in the case of clients, above).However, one thing is certain: do not mix endpoints in singular and plural.

The recommendation is that you simplify and use all names in the plural.

Use sub-resources for relationships

There are situations where one resource is related to another. This is common when there is a hierarchy of objects and resources.

For example, if it were an API that returns statistical data on the geography of a country, there could be sub-resources for states within the country and municipalities within states.

When applicable, use sub-resources in the endpoints.

For example, the requisition

GET /customers/231/projects/

must return to the 231 client's project list. And the requisition

GET /customers/231/projects/4

must return to project #4 of client 231.

Do not change states with the GET method

When performing operations that change the state of an object, use the POST, PUT and DELETE methods.

The GET method, as it is intuitive by name, should return only a read version of the resource.

HTTP offers other methods for writing to resources, so use them properly. At this point, it is important to remember the permissions and issues of API security, which brings us to our next topic:

Use SSL encryption

Your RESTful API must necessarily use SSL encryption.

Because your API web can be accessed from anywhere with Internet access, such as a shopping mall food court, a bookstore, a café or an airport, your concern is to ensure secure access to the data and services your API offers.

However, not all these locations provide secure, encrypted access.

Having the information you're carrying encrypted is essential. In addition, using SSL with tokens facilitates authentication between requests, preventing each request from being re-authenticated.

Create versions for your API

Like all software, APIs must grow and evolve. No matter how careful and experienced you are, your API will not be perfect in the first version.

And it doesn’t have to be!

Often, it's better to expose the first version of your API and gradually evolve it. However, be careful not to change its design too much and end up breaking the applications that used the previous versions (like Jeremiah Lee, from Fitbit, said in the interview to Kleber, our CEO).

Therefore, when creating a new version for your API, make sure that the previous version is still available, thus not breaking system functionality. After communicating the changes to the developers, and giving them time to adapt, old versions can be discontinued, or you can keep them on air, without offering support.

Ensure success to your API RESTful!

The 7 steps detailed above Will ensure that the onboarding (developers starting to use you API) of your API is much easier!

A final tip is that you keep an eye in the usability of you API. Check the article How to measure usability of an API.

Thanks for reading!