Designing Standard REST API's

In this article, we will be learning about the standard way of designing REST API's.

🤔 Not a long time ago, I usually design the API's according to my understanding without following any standards and consistency. It did created problem for me, when I have a bunch of API's with different designs and inconsistent Endpoints Resource Names, and I have to build a API validation function which requires consistency in all API's.

So I explored 🔍 a little, looking for the standard way of designing API's.

Finally, I have learnt to design the API's with proper standards and with consistency across all API's.

📌 Let's See How to Design and Create Standard API's.

✨ Using HTTP Methods to Define the Nature of API.

HTTP Methods should define the nature of API's whether API will be used for creating or fetching data Some Commonly used HTTP Methods:

GET - Use Get HTTP Method when API will fetch the data of a resource.
POST - Use POST Method when creating new entity.
PATCH - Use PATCH Method when updating a piece of existing data.
PUT - Use PUT Method when updating the whole entity data.
DELETE - Use DELETE Method when deleting the entity from your database.

# As you can see HTTP Methods really help in identifying the nature of API's
# Otherwise, there will be a lot of confusion in all the API's, as there URI
# is almost identical

# GET call to fetch users information
HTTP GET http://example.com/api/users

# POST call to create user entity
HTTP POST http://example.com/api/users

# PATCH call to update address of user
HTTP PATCH http://example.com/api/users/<user_id>

# PUT call to update all the information about user
HTTP PUT http://example.com/api/users/<user_id>

# DELETE call to delete the user entity
HTTP DELETE http://exmaple.com/api/users/<user_id>

✨ Using Strong and Consistent Naming Strategy.

In Rest primary data representation is called Resource. After the HTTP Method, second thing that tells you about the API is its URI or Resource Name. So, Resource Naming convention is really important as it tells a lot more about the API working.

Resource can be single or a collection.

# Collection of Resource
HTTP GET http://example.com/api/users

# Singleton Resource
HTTP GET http://example.com/api/users/<user_id>

Resource should be a noun and not verb

# Using Verb in URI ❌

HTTP GET http://example.com/api/fetch/users-data

# Using noun in URI ✅

HTTP GET http://example.com/api/users

Use - (hyphens) to increase readability of URI instead of _ (underscore)

# Using underscore in URI ❌

HTTP GET http://example.com/api/user_management/<id>

# Using hyphens in URI ✅

HTTP GET http://example.com/api/user-management/<id>

Use lowercase letters are preferable

# URI with upper case letters and lower case letter combination. ❌

HTTP GET http://example.com/API/User-Management/<id>

# URI with consistent lower case letters ✅

HTTP GET http://example.com/api/user-management/<id>

✨ Using Versioning for Breaking Changes.

When to version your API

When the request/response format changes .
When there is API functionality change.

Versioning your API's helps the other apps using your API's to upgrade to latest one as per there need. It also makes sure that no app code will break due to changes in API.

There are various ways for versioning your API:

Versioning in URI.
Versioning in Headers.
Versioning in Query params etc.

But I prefer versioning in URI as it gives more clarity to me while calling the API.

# Versioning API.
# Just add the version number of API .
# Example - we are upgrading the user management API to version 2

HTTP GET http://example.com/api/v2/user-management/<id>

# Above we have added v2 which is self explanatory that this is the second version
# of user management api

✨ Include Meta Data for Cached Response.

Caching the API really helps in reducing the latency in API response. But the only problem with caching is that one should know when to invalidate cache otherwise consumer will be getting the old response until the cache expires.

While adding caching to any API, one should add following data in response headers:

For how long the cache will be stored.
How much time is left in cache expiring.
When did the last time cache data is updated.

# Cache Meta Data in Response Headers.

Expires: Fri, 22 June 2021 19:20:49 IST  # Cache expires at given time
Cache-Control: max-age=3600         # Cache is valid for 5 mins or 3600 seconds
Last-Modified: Fri, 22 June 2021 09:17:49 IST  # Cache was updated at given time

✨ Consistent Request and Response Formats.

Consistent Request format means that you should follow one approach of accepting data all over the codebase for different HTTP Methods.

# Examples of Consistent Request format

# For GET HTTP Methods - Request params will be accepted as query strings only
HTTP GET http://example.com/api/users?age=20&gender=male

# For POST HTTP Methdos - Request params will be accepted in JSON format.
HTTP POST http://exmaple.com/api/users
#Request Body
{
    "name": "abhi",
    "age": 25,
    "gender": "male",
    "country": "India"
}

Consistent Response format means that your response format will be same irrespective of the result of API, either it breaks or works fine, response should be same.

# Example for Response format

{
    "success": True/False, # True if API is successful otherwise False
    "data": [], # Data 
    "code": "API000", # Code for errors or successful operations.
    "message": "message for consumer", # Success or fail message
    "debug_message": [], # list of debug messages for detailed information in case of error.
    "request_id": "234567890" # unique id for each request
}

✨ Concluding

Above shared Methods really helped me achieve my goal for simple and strong API calls. Do try these methods in your work, if you are also facing similar problem of inconsistent API's.

Show you love 😍 and support by liking 👍 and share this article if you find the information useful.