Understanding REST API Design Rules
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 request http:////
### URI Resource Model
Header|Description
------|-----------
Document | A 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. <br/> For example, information about a blog author is a document resource. <br/> `http://api.blog.com/authors/robin-gandhi`
Collection | A collection resource is a server-managed directory of resources. <br/> For example, a list of blog authors is a collection resource. <br/> `http://api.blog.com/authors`
Store | A store is a repository which is managed by client. Using store resource client can create, update, delete and retrieve documents. <br/> `http://api.blog.com/store/authors/robin-gandhi`
Controller | A 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: <br/> ```POST /api.blog.com/email/email/send``` <br/> ``` {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 Method | Operation |
| GET | Retrieve a resource |
| POST | Create a resource |
| PUT | Update a resource |
| DELETE | Delete a resource |
| PATCH | Update 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
```http request 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 Function | HTTP Method |
| ------------- | ----------- |
| Create | POST |
| Read | GET |
| Update | PUT |
| Delete | DELETE |
e.g. Preferred API Interface
```http request
PUT /api.blog.com/authors/robin-gandhi
Anti pattern
```http request 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:
| URI | Description |
| --- | ----------- |
| /authors | Returns a list of authors |
| /authors/robin | Returns the author details |
| /authors/robin/books | Returns 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 request
http://api.blog.com/v1/authors/robin-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 Code | Meaning | Information |
100 | 100 and above are information | 100 and above are for "Information". You rarely use them directly. Responses with these status codes cannot have a body. | 200 OK | The request was successful | 200 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 Created | The request was successful and a resource was created | 201 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 Content | The request was successful but there is no representation to return | A 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 Choices | The requested resource corresponds to any one of a set of representations, each with its own specific location | 300 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 Request | The request could not be understood by the server | 400 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 Unauthorized | The request requires user authentication | 401 is "Unauthorized". This is used when the client needs to authenticate itself to get the requested response. | 403 Forbidden | The server understood the request, but is refusing to fulfill it | 403 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 Found | The server has not found anything matching the Request-URI | 404 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 Allowed | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI | 405 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 Error | The server encountered an unexpected condition which prevented it from fulfilling the request | 500 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.