RESTful API design : Microservices

In the era of Microservices, it is essential to understand the basic of RESTful API design .REST stands for Representational state transfer .It is one of the software architectural style. In current IT industry there is no consensus on the correct way to designing the RESTful API.

We can follow some of basic principle which will bring uniformity in the API development Key Requirement for REST API .Below is the some of the requirement that a successful API should be able to address

· It uses web standards(HTTP)

· Simple and consistent to make adaptation easy

· Friendly to developer

· Flexible

· Efficient and maintain the balance with functional requirement

· Well documented

Maturity Model
Leonard Richardson has developed one modal called Richardson Maturity Modal which provides the way of using some of the REST design technique.

· Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.

· Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.

· Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.

The key principle of REST involves separating our API into logical resources. These resources are manipulated using HTTP requests where
each method (GET, POST, PUT, PATCH, DELETE) has specific meaning

Now, let’s take the topic one by one to understand RESTful API

· What are resources

· Resources content representations

· Resources singularity

· Resource relations

· HTTP Verbs

· Resource Caching

Resources: The core concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. It is a noun that makes sense to the API consumer. After the resource identification we need to apply action to them and map to our API .For example

GET /orders — Retrieves a list of orders

GET / orders /11 — Retrieves a specific order

POST / orders — Creates a new order

PUT / orders /11– Updates order with id 11

PATCH / orders /11– Partially updates order with id 11

DELETE / orders /11– Deletes order with id 11

Resources content representations

We have defined resources, and defined the data associated with them in terms of the JSON data model. However, these resources are still abstract entities. Before they can be communicated to a client over an HTTP connection, they need to be serialized to a textual representation. This representation can then be included as an entity in an HTTP message body

Below is the list of Content-type:

· JSON à application/x-resource+json application/x-collection+json

· YAML à application/x-resource+yaml application/x-collection+yaml

· XML à application/x-resource+xml application/x-collection+xml

· HTML à text/html

Resource singularity

It is pragmatic to keep the URL format consistent and to achieve that resource names should always use plural. This brings in uniformity from the API provider and consumer’s perspective.

GET / orders — Retrieves all the orders

GET / orders /11 — Retrieves order #11

Using the plural scheme will make the life of API consumer easy

Resource Relations

If a relation exists between two resources, it can represented using nested URL .Below is the example where orders and comments are two resources and how they can be represented

· GET /orders/12/comments — Retrieves a list of comments for order #12

· GET /orders/12/comments/5 — Retrieves comment #5 for order #12

· POST /orders/12/comments — Creates a new comment for order #12

· PUT /orders/12/comments/5 — Updates comment #5 for order #12

· PATCH /orders/12/comments/5 — Partially updates comment #5 for order #12

· DELETE /orders/12/comments/5 — Deletes comment #5 for order #12

Filtering and Sorting

This can be achieve using query parameters.

Filtering: GET /tickets?sort=-priority — Retrieves a list of tickets in descending order of priority

With Sorting: GET /tickets?sort=-priority,created_at — Retrieves a list of tickets in descending order of priority. Within a specific priority, older tickets are ordered first

HTTP Verbs

Following HTTP verbs are

GET — maps to a read operation. (GET /orders) Retrieves the details of a resource from the server

POST — maps to a create operation. (POST /orders) Creates a new instance of the resource on the server and returns the newly created resource. Actual contents of the resource to be created are sent as part of the request body.

PUT — maps to an update operation. (PUT /orders/{id})Updates the existing resource on the server and returns the updated version of the resource in the response. New representation of the resource is sent as part of the request body.

PATCH — maps to an update operation. This can be used when only a few fields of the resource need to be updated. (PATCH /orders/{id}). Works exactly like PUT but updates only part of a resource instead of complete overwrite.

DELETE — maps to a delete operation. (DELETE /orders/{id}). Deletes a resource from the server.

Resource Caching

It will help to reduce the round trip to the server when the response does not change It boost up the performance and reduce the load to the server .It can be acheive using API gateway or reverse proxy

Over the time API evolve and changes and expanse happens .There are several way to maintain the version

API and Resource Version

1. Url version

http://host/v1/users

http://host/v2/users

2. Version Number in HTTP request headers

GET /users/3 HTTP/1.1

Accept: application/vnd.users.v1+json

Trying to avoid long scroll on this, we still need to cover few more topics on Restful API e.g. JSON guideline, Security, documentation. I will cover it in part 2.

Happy learning …

If this post was helpful, please click the clap 👏button below a few times to show your support