Dinesh
Dinesh's Tech Blog

Dinesh's Tech Blog

REST API Design

REST API Design

Dinesh's photo
Dinesh
·Jul 19, 2022·

5 min read

Table of contents

  • API’s should be designed around resources
  • Resource URI naming
  • Resource Grouping
  • Addressing
  • Filtering
  • API operations
  • Idempotent
  • Common Response status codes
  • Data formats
  • Stateless
  • Summary

REST services are slowly becoming the norm. With the raise of SPA (Single Page Applications), REST API's have become the main way of consuming data.

These APIs are designed around resources. A resource can be an object, data, or service that can be accessed by the client. A resource has an identifier, which is a URI that uniquely identifies that resource. For example, the URI for a todo might be

https://todo.com/todos/1

Clients interact with a service by exchanging representations of resources.

Many web APIs use JSON as the exchange format. XML was used before, but now it's mostly JSON.

It makes use of HTTP verbs to perform operations on resources. The most common operations are GET, POST, PUT, PATCH, and DELETE.

API’s should be designed around resources

Let’s take an example of a TODO application. In this application, todo is a resource. If we need to create a todo, we will make a POST API call to https://todo.com/todos API & the response status code will indicate the status of the action.

Resource URI naming

Resource URI’s should be based on nouns and not on actions. Use plural form of the resource.

Bad

 https://todo.com/create-todo

Good

 https://todo.com/todos

Resource Grouping

Let’s say our TODO app, allows users to group todo’s into a list. In that case the URI will look like this

 https://todo.com/lists/{listId}/todos

From the URI you can see that, there is a hierarchy. In the above example we are addressing all the todos from the list {listId}.

Addressing

Resources can be addressed individually with the resource id or all of them can be fetched at once when the id is not specified.

Fetch all TODO's

 GET https://todo.com/todos

Fetch a specific TODO

 GET https://todo.com/todos/1

Filtering

We have an API to get all TODO’s. Now, what if you want to fetch only the completed todo's ? This is where we use resource filtering.

 GET https://todo.com/todos?status=complete

Resources can be filtered by using query string in the URI.

API operations

Here's is a table which describes the HTTP methods used and the description of when each one of them should be used.

HTTP MethodDescription
GETFetch one or all resources specified in the URI
POSTCreate a new resource
PUTCreate or Update resource at the specified URI. PUT request must be idempotent
PATCHPartial update of the resource
DELETEDelete the specified resource

Both POST & PUT can be used to create a resource. The difference being, when a resource is created using a POST request, the resource identifier is assigned by the server. But when a resource is created using a PUT request, the identifier provided in the URI will be used.

Resource ID will be assigned by the server

POST https://todo-app.com/todos

Resource ID 121 provided in the URI will be used

PUT https://todo-app.com/todos/121

The following table summarizes the common conventions adopted by most RESTful implementations using the todo example. Not all of these requests might be implemented—it depends on the specific scenario.

ResourceGETPOSTPUTDELETE
/todosRetrieve all todosCreate a new todoBulk update of todosRemove all todos
/todos/1Retrieve the details for todo 1ErrorUpdate the details of todo 1 if it existsRemove todo 1
/todos/1/tasksRetrieve all tasks for todo 1Create a new task for todo 1Bulk update of tasks for todo 1Remove all tasks for todo 1

Idempotent

An HTTP method is said to be idempotent if the same request can be made multiple times in a row resulting in the same effect. In other words, an idempotent method should not have any side-effects.

Let's take an example:

POST https://todo.com/todos

If you make this api call 10 times (with the same request body), then you would find 10 different resources in the server. This is because POST is not idempotent and for every request it will create a new resource.

PUT https://todo.com/todos/121

In this case, no matter how many times the API is called (with the same request body), there will be only 1 resource and with the same data.

GET, PUT & DELETE are idempotent methods. Make sure that PUT method is always idempotent.

Common Response status codes

The client determines the status of a request by looking at the response status code. Here are the most commonly used one's.

CodeCode StringDescription
200OkRequest success
202AcceptedUsed for asynchronous operations
204No ContentDelete success or no response body
400Bad RequestValidation error
401UnauthorizedUser not logged in
403ForbiddenUser does not have access to the resource
404Not FoundResource not found

404 is sometimes used when a user tries to access a forbidden resource. This is done, so that a malicious user doesn't figure out that a resource actually exists.

Data formats

xml & json are the 2 major data formats. In 2022 json is the widely used format.

Stateless

REST API's should be stateless. Everything needed is within the request. Also the requests should be atomic. This enables web services to scale very well, as any server can take & process the request.

Summary

I hope this post has given you an overview of REST API Design. There is no fixed standard for REST, but there are commonly adopted guidelines and conventions.

References

 
Share this