The Dev World – Sergio Lema

The RESTful interface is not just sending JSON data.

A RESTful communication is about standards, naming strategies and readability.

It can even be in XML or TXT format.

In this article, I list 5 points to build a RESTful-compliant application.

Use The Correct HTTP Verbs

There are many HTTP verbs: GET, POST, PUT… All have a different meaning and usage.

Using the GET verb to save a new vehicle in the database makes no sense.

Not using the adequate verb makes the API harder to read and understand. Each verb has its meaning and usage. In this article, I explain each one in detail.

Use The Correct Nouns

The URL must always reflect the item I want to handle. If I want to read books, GET /books. If I want to create a new vehicle, POST /vehicles.

I rarely use singular nouns, because I want to read all the books or create a new vehicle into the existing dataset of vehicles.

What happens when I need a single book? GET /books/<Id>. From all the books, I want the one with this Id.

I must use the same naming convention used in the team. If everybody uses the vehicle noun, I can’t use car in my URL.

Use Hierarchy

Using nouns to define the entities is good. But, using one noun for each entity is more complicated.

At some point, I need to use several nouns to read entities or to group them.

What if I want all the vehicles of a country? What if I want only the brand of a vehicle?

In those cases, I need to use the hierarchy:

• For all the vehicles of a country, /country/<code>/vehicles
• For the brand of a single vehicle, /vehicles/<Id>/brand

I have to pay attention to the order, as the vehicles belong to a country, and the brand is from the vehicle. The parent is always on the left.

When Actions, End With Verbs

Now I can build endpoints to read any property, to search, and to create entities.

But an application has many other purposes, and many other actions.

I need verbs to describe those actions.

• If I need to export all the vehicles, /vehicles/export
• If I need to buy all the items in a basket, /basket/<Id>/buy

What verb do I need to use? Usually POST. Because it performs actions on the server, that might not be idempotent.

Use The Correct HTTP Response Code

Last topic. Until now, I’ve only spoken about the request. But a RESTful API is also about the response.

I have the HTTP verbs and URL that define the request. And I have the HTTP response code that defines my response.

The most used one is 200, which means OK, everything went fine. I can use it in almost all the cases.

But there are other important HTTP response codes.

The response codes are grouped into 4 categories:

• 2xx for Ok,
• 3xx for moved entities,
• 4xx for errors made by the user,
• and 5xx for errors made by the server.

I describe in detail the most used HTTP response codes in this article.

Conclusion

As always in programming, it’s all about readability. A RESTful API must be easily understood by a newcomer. Following the standards and having a strong naming strategy are the keys.