RESTful APIs: Specification

Overview

In modern era, micro-service architecture is being followed in most of the system designs. Which leads to build small separate services(based on functionality) instead of standalone giant application. The job of any service is to serve(process and respond) client based on the request, so there is something known to both the parties(front end or other services and server) is an APIs.

APIs(Application Programming Interface) is an end-point(interface) of a service through which client can interact with server application. There could be a thousands of endpoints designed and ready to serve in an application. There are many architectures [RESTful, SOAP etc.] and protocols available about APIs which focus on Specifications of APIs like how it should be designed.

Brief History

In 2000, Roy Fielding proposed Representational State Transfer(REST) as an architectural approach to designing web services.

In This post some specifications mentioned which can be followed in order to design REST APIs.

Good APIs process around given resources.
It does not store any information regarding resource once it is served to client (statelessness).
It should be understandable(respond in valid format) so that any client can consume it.

In RESTful APIs architecture, URI contains some details of resources in form of query or path parameters also. Main or Basic design principle of RESTful APIs using HTTP is

Every resource should have unique identity(URI).

https://www.blogger.com/user/12/blog/post/123

Let's take above URI as an example, one can interpret URI as process on 123rd post of blog of user 12(number as ids). Here user, blog and post are resources.

Possible HTTP operations could be GET, POST, DELETE, PUT, PATCH or OPTIONS for Uri. Each methods have different use-cases.

Operations	Description
GET	Retrieve resource.
POST	Create new resource
PUT	Modify resource.
DELETE	Delete resource.
OPTIONS	Used to validate does client has permission to make a request to the server and resource present on the server.
PATCH	Used to modify resource but it is not idempotent(result could be different for same request).

Even though one can use POST operation for all the request, that is not good practice. Above description is general and very basic for HTTP method. Generally OPTIONS are used by browser(client) before making POST call and one of the reason is security also.

Client interacts with server by exchanging resource's representational state. It could be in JSON or XML format which are widely used and supported. Client sends resource in request body or receive in response body.

REST APIs use a stateless request model. HTTP requests should be independent and may occur in any order. The only place where information is stored is in the resources themselves, and each request should be an atomic operation.

There is maturity model proposed by Leonard Richardson which has 4 levels starting from 0.

Levels	Descriptions
0 level	All operations are POST for each Uri.
1 level	Separate Uri for different resources.
2 level	Use HTTP operations(Methods) to process resources.
3 level	Uses hypermedia (Response contains Uris of other resources associated with requested resource).

Example

If one wants to design an Restful API which stores data of article to data store. There could be 2 possible ways.

1. https://www.blogger.com/user/12/blog/create-post/123 // avoid

2. https://www.blogger.com/user/12/blog/post/123 // readable and best practice to follow

Here our resources are user, blog and post.

We can use POST operation for both the Uri but 1st Uri is more verbose then 2nd. we can use 2nd Uri with other operations like DELETE to delete post data from the data store, PUT to edit post data or GET to fetch post data. Use 1st Uri with other operations can be misleading for client and one can not directly find out what Uri is serving.

Media Type and Status Code

Client and server needs additional data with Uri to understand and parse payload or response body which is Content-Type. Content-Type is passed in header by client. Client can send other header called Accept which means client understands(parse) given media type only. If server can not response back in form of media type present in accept header then it can response with status code 406 (Not Acceptable).

GET request response with 200(OK) status code if resource found or else 404 (Resource Not found).

POST request creates resource so it response with 201(Created) status code. In case of empty response body server sends 204 (No Content).

Above specifications are not mandatory but it is good to follow.