How To Design a REST API?

APIs are now a must-have concept in application development. In this article, we will see how to design a REST API.

We will first briefly explain some key concepts to better understand how REST APIs work, including the HTTP protocol, the definition of a resource and a collection. After that we will explain one way to design a REST API.

Table of contents

1.The HTTP protocol

2. Resource and Collection

3. How to design a REST API?

4. The documentation

5. In conclusion

1. The HTTP protocol

In this first part, we will talk about the HTTP protocol which is the communication protocol used by REST APIs.

HTTP is a communication protocol that works in client-server mode, i.e. you have a client (e.g. a web browser) that sends a request to the server (e.g. an Apache server), the server processes this request and sends a response back to the client.

We will explain what an HTTP request and an HTTP response are, and how they are structured.

The HTTP request

An HTTP request is structured in a certain way so that the server can understand it. It is composed of three parts :

1. The command line : it contains the method, the path and the protocol version.
2. The request header : contains a set of optional lines allowing to give additional information about the server or the client.
3. The body of the request : contains a set of optional lines, which correspond to data that is sent through a form.

A method is a command that specifies the type of request, i.e. what the server should do. For example, retrieve a resource or save it. There are several methods, but we’ll just mention the ones we’ll use next:

 – GET : this method is used to request a resource (we will see what a resource is in the next section), it has no effect on the resource

– POST : it is used to transmit data, the result can be the creation of a new resource.

– PUT : this method can be used to replace or add a resource.

– PATCH : this method is used when you want to partially modify a resource.

– DELETE : this is the method used to delete a resource.

The HTTP response

An HTTP response is also structured in a certain way, it also consists of three parts:

1. The response line : it includes the protocol version, the status code and the meaning of this code.
2. The response header : it contains optional lines giving additional information about the response and/or the server.
3. The body of the response : it can contain the document or the resource requested.

The status of the response indicates whether the request was successful or not. They are grouped into five groups:

• 1xx : indicates information
• 2xx : indicates that the request was successful
• 3xx : indicates a redirection of the request
• 4xx : indicates that an error has occurred, but that the cause is the client’s
• 5xx : indicates that an error has occurred, but that the cause comes from the server

Among these status codes, you have one that is very well known : the 404 code which indicates that the client has requested a non-existent resource.

2. Resource and Collection

• A resource represents any type of name that can be used to represent data in an application. For example, we can have the user resource represent the data of a user, or the article resource represent the data of a post.
  Each resource contains additional information about the data it contains. For example, for a user resource you can have as additional data, his first name, his last name and his age.
• Resources are grouped together in a group called a collection. This is the plural of the resource name. For example, for the user resource we have the collection users, or for the product resource we have the collection products.

Now that we’ve covered a few concepts, let’s see how to design a REST API.

3. How to design a REST API?

First of all, what is an API? We can define an API as an interface that exposes all the services of a software. The particularity of REST APIs is that the HTTP protocol is used for communication, and the JSON format is used to structure and exchange data.When designing a REST API, we can answer the following three questions:

1. How to represent the data?
2. How to name the paths to a resource?
3. How do we expose the methods?

How to represent the data?

Data is at the core of an application, so the first thing to do is to find a consistent way to represent it. How do you do that?First, we will split the data into several elements that we will represent as resources. Each resource will have a name and will contain additional information about the data it contains.

Secondly, the resources will be gathered into a collection. We refer to a collection with the form of the resource name in the plural.

How to name the paths to a resource?

To allow a client to access resources, our API will expose methods. Each method is called through what is called a path. The job here will be to find a consistent way to name these paths. There are several good ways to do this but, we will choose the following : /api/<the API version>/<the collection name>.

How do we expose the methods?

Once the data representation has been defined, the methods to be exposed to access and manipulate the data must be determined.
We will first define the nature of our methods. Each method must perform an action, the nature of an action being defined by an HTTP verb. Here is how we will define and expose the methods for our Shoes collection:

• GET /api/v1/shoes : to get the collection
• GET /api/v1/shoes/123 : to get the shoe with id 123
• POST /api/v1/shoes : to add a resource to the collection
• PUT /api/v1/shoes/123 : to modify the shoe resource with id 123
• DELETE /api/v1/shoes/123 : to delete the shoe resource with id 123

Next, we need to determine if the client needs to authenticate itself in order to call a method. To do this, the user must provide their information in the request header.

And finally, we need to determine the errors that may occur when a method is called. The nature of an error must be able to be determined by the client through a status code in the header, and a message in the body of the response.

Example: we will use the collection shoes

4. The documentation

Once we have finished designing our API, and moved on to development, it is important to provide documentation for our API. In terms of documentation, the most important information is the following:

• The API version
• Available resources: for each resource, the data it represents must be documented
• The available methods: for each method, the definitions of the request, the response, and the different response statuses must be described.

For the documentation of your API, there are technologies that can generate it. The one I use in my projects is Swagger, it is very used and can be integrated in many frameworks.

5. In conclusion

• An API is an application that exposes services through an interface. A REST API uses the HTTP protocol for communication and the JSON format to structure and exchange data.
• The first step in designing a REST API is to represent the data. We need to organize the data into resources, and group these resources into collections.
• The second step is to find a naming standard for the paths.
• The third step is to define the methods to be displayed for the different collections.
• When the API is deployed, it must be accompanied by a documentation page.

To go further with REST APIs, I invite you to watch this video, and this excellent book by Philip Sturgeon on API design.