Declaration: This is not an original piece of work but a set of notes derived from the original sources as mentioned in the link.

What Does RESTful API Mean?

"RESTful" implies a few features:

Client-server architecture: The complete service is comprised of the "Client" which is the front-end and the "Server" which is the backend part of the whole system.
Stateless: The server should not save any states between different requests. The state of the session is exclusively left to the responsibility of the client. As per the definition of REST: All REST interactions are stateless. That is, each request contains all of the information necessary for a connector to understand the request, independent of any requests that may have preceded it.
Cacheable: The client should be able to store responses in a cache for greater performance.

So, the RESTful API is a service that follows these rules (hopefully) and uses HTTP methods to manipulate the set of resources.

Characteristics of a good API

Easy to read and work with: A well designed API will be easy to work with, and its resources and associated operations can easily understood by end consumers.
Hard to misuse: Implementing and integrating with an API with good design will be a straightforward process, and writing incorrect code will be a less likely outcome.
Complete and concise: A complete API will make it possible for developers to make full-fledged applications against the data you expose.

HTTP methods and it’s meaning

GET - retrieves a representation of the resource at the specified URI. The body of the response message contains the details of the requested resource.
POST creates a new resource at the specified URI. The body of the request message provides the details of the new resource. POST can also be used to trigger operations that don't actually create resources.
PUT either creates or replaces the resource at the specified URI. The body of the request message specifies the resource to be created or updated.
PATCH performs a partial update of a resource. The request body specifies the set of changes to apply to the resource.
DELETE removes the resource at the specified URI.

Best practices for REST APIs

Abstract vs Concrete APIs

Let's look at two API versions. Is it better to have an API that has one /entities or an API that has /owners, /blogs and, /blogpostsseparately?

Which one seems more descriptive to you as a developer? Which API would you rather use?

URI Formatting (Nouns, not Verbs): Good URL vs Bad URL Examples

Bad endpoint examples

/getAllBlogPosts

/updateBlogPost/12

/deleteBlogPost/12

/getAuthorById/3

/deleteAuthor/3

/updateAuthor/3

Good endpoints examples

GET /blogposts - gets all the blog posts.

GET /blogposts/12 - gets the blog post with the id 12.

POST /blogposts - adds a new blog post and returns the details.

DELETE /blogposts/12 - removes the blog post with the id 12.

GET /authors/3/blogposts - gets all the blog posts of the author with id 3.

Error Handling

This is another important aspect of API building. There are a few good ways to handle errors.

Status Codes

Should you have a strict status code for every situation?There are over 70 status codes out there. Do you know them by heart? Will the potential API user know them all?

Most developers are familiar with the most common status codes:

200 OK
400 Bad Request
500 Internal Server Error

By starting with these three, you can cover most of the functionalities of your REST API.

Other commonly seen codes include:

201 Created
204 No Content
401 Unauthorized
403 Forbidden

It’s recommended to help the user by using a limited number of codes and descriptive messages

REST API Versioning

This approach is a great way to introduce new changes while letting some users continue with old versions. Before you start making your API, you can version your API by prefixing the endpoints by the API version:

https://api.example.com/v1/authors/2/blogposts/13

This way you can always increment your API version number (eg. v2, v3...) whenever there are breaking changes in your API. This also signals to the users that something drastic has changed and they should be careful when using the new version.

Use Proper HTTP Headers for Serialization Formats

Both client and server need to know which format is used for communication. The format has to be specified in the HTTP-Header.

Content-Type defines the request format.

Accept defines a list of acceptable response formats.

Get Method and Query Parameters Should Not Alter the State

We must use PUT, POST and DELETE methods instead of the GET method to alter the state. Do not use GET for state changes:

GET /users/711?activate or GET /users/711/activate etc are wrong

Use Sub-Resources for Relations

If a relation can only exist within another resource, RESTful principles provide useful guidance. If a resource is related to another resource using subresources.

GET /cars/711/drivers/ Returns a list of drivers for car 711

GET /cars/711/drivers/4 Returns driver #4 for car 711

Other examples:

GET /tickets/12/messages - Retrieves a list of messages for ticket #12
GET /tickets/12/messages/5 - Retrieves message #5 for ticket #12
POST /tickets/12/messages - Creates a new message in ticket #12
PUT /tickets/12/messages/5 - Updates message #5 for ticket #12
PATCH /tickets/12/messages/5 - Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5 - Deletes message #5 for ticket #12

Searching, Sorting, Filtering, and Pagination

All of these actions are simply the query on one dataset. There will be no new set of APIs to handle these actions. We need to append the query params with the GET method API. Let’s understand with a few examples of how to implement these actions.

Sorting - In case, the client wants to get the sorted list of companies, the GET /companies endpoint should accept multiple sort params in the query. E.g GET /companies?sort=rank_asc would sort the companies by its rank in ascending order.

Filtering - For filtering the dataset, we can pass various options through query params. Example: GET /companies?category=banking&location=india would filter the companies list data with the company category of Banking and where the location is India.

GET /employees?state=internal&title=senior

GET /employees?id=1,2

The JSON:API way of filtering is:

GET /employees?filter[state]=internal&filter[title]=senior

GET /employees?filter[id]=1,2

Searching - When searching for the company name in companies list the API endpoint should be GET /companies?search=Digital .

Pagination - When the dataset is too large, we divide the data set into smaller chunks, which helps in improving the performance and is easier to handle the response. Eg. GET /companies?page=23 means get the list of companies on 23rd page. A really simple approach is to use the parameters offset and limit, which are well-known from databases.

/employees?offset=30&limit=15 # returns the employees 30 to 45.

If the client omits the parameter you should use defaults (like offset=0 and limit=100). Never return all resources. If the retrieval is more expensive you should decrease the limit.

/employees # returns the employees 0 to 100

Use Consistently Plural Nouns

Prefer

/employees

/employees/21

over

/employee

/employee/21

Format to use Rest API URL

http(s)://{Domain name (:Port number)}/{A value indicating REST API}/{API version}/{path for identifying a resource}

http(s)://{Domain name indicating REST API(:Port number)}/{API version}/{path for identifying a resource}

Good API Reference

https://developer.paypal.com/docs/api/orders/v2/

Documentation

We should always have proper documentation for our APIs. For example:

Swagger is another tool that can be explored

References:

https://dzone.com/articles/top-rest-api-best-practices

https://phauer.com/2015/restful-api-design-best-practices/