Skip to main content

Understanding REST API Design Rules

· 11 min read

Introduction to REST API

REST (Representational State Transfer) is an architectural style for building distributed systems. A Web API conforms to the REST architectural style, called RESTful Web API.

REST APIs are stateless, client-server, cacheable, layered systems designed around resources. The set of resources is known as the REST API's resource model

REST APIs are one of the most common and fundamental ways to expose data and functionality as web services. REST APIs use HTTP requests to GET, PUT, POST, and DELETE data.

An adequately designed REST API should be easy to understand, use, and evolve over time. It will help clients and browser apps consume the API more efficiently.

Before designing and developing a REST API, we need to seek answers to the following questions:

  • What are URI Paths? Structure of URI Path segments?
  • When to use plural nouns or verbs for URI Path segments?
  • What is the HTTP response status code, and how to use it in a specific scenario?
  • How to map non-CRUD operations to HTTP methods?

Understanding Uniform Resource Identifier (URI)

REST APIs use Uniform Resource Identifiers (URIs) to identify resources. A resource is any information that can be named. Resources are separated by forward slashes (/). A good URI should be short, easy to remember, and should give the user an idea about the resource.

URI Format

The URI format is as follows:

URI = scheme "://" host [ ":" port ][ "/" path ] [ "?" query ][ "#" fragment ]

http://<domain-name>/<resource-name>/<resource-id>

URI Resource Model

HeaderDescription
DocumentA document resource is similar to database record or instance of an object. It is a single resource that can be retrieved, created, updated, or deleted.
For example, information about a blog author is a document resource.
http://api.blog.com/authors/vishal-gandhi
CollectionA collection resource is a server-managed directory of resources.
For example, a list of blog authors is a collection resource.
http://api.blog.com/authors
StoreA store is a repository which is managed by client. Using store resource client can create, update, delete and retrieve documents.
http://api.blog.com/store/authors/vishal-gandhi
ControllerA controller resource models a procedure concept. It is a resource that represents a procedure that can be invoked. A controller resource is a collection resource that supports the POST method. The POST method is used to invoke the controller resource. The controller resource can be used to model a procedure that can be invoked. For example, the following URI models a controller resource that represents a procedure that can be invoked to send an email:
POST /api.blog.com/email/email/send
{Collection}/{Store}/{Document}/{Controller}

REST API Design Rules

URI

  • Rule : Forward Slash (/) is used to separate resources in the URI and indicate a hierarchical relationship

A trailing forward slash (/) is not required as the last character of a URI. Many web servers automatically redirect requests with a trailing forward slash to the same URI without the trailing forward slash.

  • Rule : Use plural nouns for URI Path segments that represent collections or resources

  • Rule : Use HTTP Methods to Perform Operations on Resources

HTTP methods are used to perform operations on resources. The following table lists the HTTP methods and their corresponding operations:

HTTP MethodOperation
GETRetrieve a resource
POSTCreate a resource
PUTUpdate a resource
DELETEDelete a resource
PATCHUpdate a resource with Partial data
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const port = 3000;

app.use(bodyParser.json());

app.get('/authors', (req, res) => {

res.send('Authors List');

//get author list from Sql lite backend

res.json(authors);

});

app.post('/authors', (req, res) => {

res.send('Add Author');

//add author to Sql lite backend

res.json(author);

});


//update an author

app.put('/authors/:id', (req, res) => {

res.send('Update Author');

res.json(author);

});

//delete an author

app.delete('/authors/:id', (req, res) => {

res.send('Delete Author');

res.json(author);

});

app.patch('/authors/:id', (req, res) => {

res.send('Update Author Email');

res.json(author);

});


app.listen(port, () => {
console.log(`Blog Example app listening at http://localhost:${port}`);
});
  • Rule : Hyphen (-) is used to separate words in URI Path

Hyphens (-) are used to separate words in URI path. For example, the URI path for a resource named user-profile is /user-profile.

  • Rule : Underscore (_) is not used in URI

Underscores (_) are not used in URI path due to text editors and browsers depending on the font hide the underscore by underlining the text.

  • Rule : File Extensions are not used in URI

A REST API should not use file extensions in the URI. For example, the URI path for a resource named user-profile is /user-profile and not /user-profile.json.

  • Rule : If API Provides a developer portal then it should be accessible via a consistent subdomain

If an API provides a developer portal, then the developer portal should be accessible via a consistent subdomain. For example, the developer portal for the weather API is accessible via developer.blog.api.com.

  • Rule : Lowercase letters are preferred in URI

Lowercase letters are preferred in URI. For example, the URI path for a resource named user-profile is /user-profile and not /User-Profile.

  • Rule: Use a Verb or verb phrase for Controller Names
POST /api.blog.com/email/email/send
  • Rule: CRUD function names should not be used in the URI

The following table lists the CRUD functions and their corresponding HTTP methods:

CRUD FunctionHTTP Method
CreatePOST
ReadGET
UpdatePUT
DeleteDELETE

e.g. Preferred API Interface

PUT /api.blog.com/authors/vishal-gandhi

Anti pattern

DELETE /deleteusers/abc/
  • Rule: New URIs should be introduced new concepts

A REST API should introduce new URIs for new concepts. For example, the following table lists the URIs for a user resource:

URIDescription
/authorsReturns a list of authors
/authors/vishalgandhiReturns the author details
/authors/vishalgandhi/booksReturns a list of articles written by the author
  • Rule: JSON should be well formed and supported for resource representation

  • Rule: Add Versioning at the start of the URI


http://api.blog.com/v1/authors/vishal-gandhi

HTTP Methods

  • Rule: GET must be used to retrieve representation of a resource

  • Rule: Head must be used to retrieve metadata of a resource and response headers

  • Rule: PUT must be used to both insert and update a resource

  • Rule: POST must be used to create a resource

  • Rule: POST must be used to execute a controller

  • Rule: DELETE must be used to delete a resource

  • Rule: OPTIONS must be used to retrieve supported HTTP methods

  • Rule : Use HTTP Status Codes to Indicate Response Status

HTTP status codes are used to indicate the response status of an HTTP request. The following table lists the HTTP status codes and their corresponding meanings:

HTTP Status CodeMeaningInformation
100100 and above are information100 and above are for "Information". You rarely use them directly. Responses with these status codes cannot have a body.
200 OKThe request was successful200 and above are for "Successful" responses. These are the ones you would use the most. 200 is the default status code for a successful response.
201 CreatedThe request was successful and a resource was created201 is "Created". This is used when a new resource is created. The response will contain a Location header with the URI of the new resource.
204 No ContentThe request was successful but there is no representation to returnA special case is 204, "No Content". This response is used when there is no content to return to the client, and so the response must not have a body.
300 Multiple ChoicesThe requested resource corresponds to any one of a set of representations, each with its own specific location300 and above are for "Redirection". These are used when the client needs to take some additional action in order to complete the request. For example, if you request a resource that has been moved to a different location, the response will be 301, "Moved Permanently", and the response will contain a Location header with the new location of the resource. The client can then make a new request to that location.
400 Bad RequestThe request could not be understood by the server400 and above are for "Client Error" responses. These are used when the client has made a mistake in its request. For example, if you request a resource that doesn't exist, the response will be 404, "Not Found".
401 UnauthorizedThe request requires user authentication401 is "Unauthorized". This is used when the client needs to authenticate itself to get the requested response.
403 ForbiddenThe server understood the request, but is refusing to fulfill it403 is "Forbidden". This is used when the client is not allowed to access the resource. For example, if you try to access a resource that you don't have permission to access, the response will be 403, "Forbidden".
404 Not FoundThe server has not found anything matching the Request-URI404 is "Not Found". This is used when the client requests a resource that doesn't exist. For example, if you request a resource that doesn't exist, the response will be 404, "Not Found".
405 Method Not AllowedThe method specified in the Request-Line is not allowed for the resource identified by the Request-URI405 is "Method Not Allowed". This is used when the client requests a resource using a method that isn't allowed. For example, if you try to access a resource using the POST method, but the resource only supports the GET method, the response will be 405, "Method Not Allowed".
500 Internal Server ErrorThe server encountered an unexpected condition which prevented it from fulfilling the request500 and above are for "Server Error" responses. These are used when the server encounters an error while fulfilling the request. For example, if the server runs out of memory while fulfilling the request, the response will be 500, "Internal Server Error".

The approaches and best practices of REST API outlined in this blog article will help anyone follow consistent guidelines for designing and developing REST APIs.

References