What is REST API? How to design a RESTful API?

1. What is REST API?

REST API (also known as RESTful API) is an application programming interface (API) that adheres to the REST architectural conventions and constraints used in client-server communication. REST stands for REpresentational State Transfer, it was created by computer scientist Roy Fielding.

REST APIs typically still use the HTTP/1 protocol with previous definitions that both the client and the server need to adhere to. For example, the server provides an API to get the balance of an account, the method is GET, it should have the Authorization header, the response will be text with the first part being the account number, the second part the balance.

The time that returns text like that is over, now the REST API uses JSON more commonly. A few may still exist and use XML.

2. Components in REST API (2)

API (Application Programming Interface) translates as an application programming interface. Actually, this interface is not for end-users but for developers. Rather, it is just a “surface”, only the declaration (name, parameters, return type) can be seen, the body is unknown. “See the box, don’t know what’s inside” is the API.

REST (REpresentational State Transfer) means a representation of data transformation. What the hell!! That is to say, in this architecture, the client and server are completely independent, they don’t know anything about each other. Each REST API request carries no previous state (stateless). So for the two parties to exchange state, they will force through resources. These resources are the representation of data changes.

REpresentational State Transfer

3. Request and Response in REST API

3.1 Methods

As mentioned above, to exchange states they will need to communicate resources through sending request responses via HTTP/1. Specifically, how this communication is, they need to specify the corresponding methods including:

• GET: return a Resource or a list or Resource
• POST: create a Resource
• PUT: update a Resource (fully)
• PATCH: update a Resource (partially)
• DELETE: delete a Resource

If you have heard of CRUD API, it stands for Create, Read, Update and Delete any resource.

3.2 Header: Authentication and specify the return data type

Remember that REST API is stateless. Each request does not know any prior information. Unlike when we visit the web, the browser will have a session and a cookie to support the request to distinguish who it is from and what the previous information is.

In REST, if a request needs to authenticate access, they will have to use additional information in the header. For example, the Authorization information will carry a user token. There are 3 main Authentication mechanisms:

• HTTP Basic
• JSON Web Token (JWT)
• OAuth2

In addition, the Header also helps the client specify the type of content to return from the server — content type. This is done through the Accept section of the header. Its value is usually the MIME type:

• image — image/png, image/jpeg, image/gif
• audio — audio/wav, audio/ mpeg
• video — video/mp4, video/ogg
• application — application/json, application/pdg, application/xml, application/octet-stream

Example request get list posts:

GET /v1/posts
Accept: application/json

3.3 Status Code

The response in the REST API will include a status code that specifies each case. You can see the full list here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Some popular statuses:

• 200 OK — Returns success for GET, PUT, PATCH, or DELETE methods.
• 201 Created — Return success for POST methods
• 204 No Content — Returns when the Resource is successfully deleted.
• 304 Not Modified — The client can use the data cache, the resource server doesn’t change anything.
• 400 Bad Request — Invalid request
• 401 Unauthorized — The request requires authentication.
• 403 Forbidden — Denied permission.
• 404 Not Found — Resource not found from URI
• 405 Method Not Allowed — The method is not allowed for the current user.
• 410 Gone — Resource no longer exists, old Version is no longer supported.
• 415 Unsupported Media Type — This resource type is not supported.
• 422 Unprocessable Entity — Data not validated
• 429 Too Many Requests — Request denied due to restriction

3.4 Version support

Usually, REST API will have versions like /v1, /v2 to support older data versions. This is especially important when we upgrade the API to higher versions, this upgrade can make a huge difference: changing the URL, how the user is authenticated, or both the resource name and its structure.

4. How to design REST API according to the convention

Although the constraints and conventions on developers do not need to adhere to. However, if done “right”, they will bring a lot of benefits.

4.1 Designing REST API URI

I have seen a lot of REST API designs written like this:

POST /create_post (create post)
GET /list_posts (get list of posts)
POST /feature_posts (list of feature posts)
POST /edit_post/:post_id (edit post with a post with id)

These REST APIs are still working fine, no problem!! Only they don’t follow the convention. This leads to a hassle for the document maker (or the designer himself) to double-check that the URL is correct. The API user side must also set up an API list as well.

Compare that with the following URL design:

POST /v1/posts (create a new post)
GET /v1/posts (get list of posts)
GET /v1/posts/:post_id (get list of a post with id)
PUT /v1/posts/:post_id (update a post with id)
DELETE /posts/:post_id (delete a post with id)

In this way of designing you will see that there is a very clear principle of using request methods to tell the mission of the API. The URI part can be the same, no need to contain verbs like: create, get, update, delete anymore. Resource name will be in the plural form (plural).

Some other examples:

GET /v1/posts/:post_id/liked-users (get list of users that like a specific post with post_id)
POST /v1/posts/:post_id/liked-users (like a specific post with post_id)
GET /v1/posts?page=2&limit=50 (use query string to filter or paginate)

4.2 Other conventions:

• Use the correct Status Code. If the API returns an error, please use the correct status, avoid always returning 2xx status when the body is an error message (this is a lot of you are doing it wrong).
• Don’t use underscore “ _ “, use hyphen “ - “in URI (liked-users instead of liked_users)
• URIs are all lowercase letters.
• Do not use file extensions (extensions) in URIs (eg .html, .xml, .json).