REST API Best Principles

As we are using REST APIs more and more nowadays, I thought of listing some of REST APIs best principles or practices that developer should take care of while designing/developing REST APIs. Please feel free to provide your thoughts.

1.       URI -

a.       Name versus Verb - Concrete names should be used for Resource name instead of action verbs. e.g. if API is to get users, it should be GET /USERS and not getUsers

b.       Singular versus Plural - There is always debate on if singular noun should be used or plural for the resource name. I think answer is that it depends. e.g. if GET API might return the list then it should be plural. But if API is for single object e.g. Cart, then it could be singular. In general, plural will provide more flexibility to return single or multiple records.

c.       Spinal case versus camel case - Shall we use camel case(like Java) or spinal case(-)? I think it is individual preference. But some of the rest principles encourage using spinal case in the name e.g. URI to return current user could be current-user instead of CurrentUser. current-user name provides more readability than CurrentUser

2.       Versioning -

Versioning is very important in the API design as APIs are always going to change in future. So good design should consider versioning so that new feature/attributes could be added in the API in future without impacting consuming systems.

There are different ways of adding versioning -

a.       Versioning could be added in the URI like below.  Advantages of using versioning in URI is that it is crystal clear to the developers about the version they are using. I personally liked displaying version visually in the URL instead of putting it in header.

https://example.org/api/v1/*

b.       Adding versioning in content-type e.g. application/json+v1. Disadvantage of this is that only developer knows the version since version is not displayed in the URI.

c.       Using custom header - versioning could be added in the custom header too.

3.       Cacheable -

Caching is critical for the API as proper caching reduces load on the server and improving the performance of the API. Developers should know if API is cacheable or not. If it is cacheable, when they should renew the cache. This information could be passed through headers like Cache-Control and Expires header.

Cache-Control header could be used to declare if cache should be public or private (used with CDNs) or whether or not the data should not be cached (no-cache) or stored (no-store). We can have a max-age (in

seconds) for which that the data should be stored and a number that is designed to override the Expires header.

4.       Documentation -

APIs are of no use to anyone until documented. Detailed and upto date documentation is important for the APIs. There are many tools like Swagger or readme etc which provide platform for API documentation. There are other tools like MuleSoft API designer which allows developer to design the API specification and mock them up. It is worth spending time on API specification before developing it.

5.       Status codes -

HTTP provides lot of predefined status codes for different scenarios. So it is important to return correct status code. e.g. if a POST API is called and a resource is created, then API can return 201(Created) along with resource id instead of 200(OK).

It is important to return proper error code, messages in case of any error. It helps consumers of the API in investigating and resolving the issue.

6.       API Gateway - Last and one of the most important point is to protect your API. We should put gateway which will front face the APIs. Consuming system needs to call API Gateway url which will delegate request to actual APIs after checking for some policies. API Gateway could help in authentication/authorization, throttling and rate limiting etc. Our APIs will be secure since consuming system can not directly access the API and we can define rate limit policy in API Gateway. e.g. if API access is limited to 100 times a day for a consuming system and system tried to access it 101 time, API gateway will return error to the system.