Building RESTful APIs - Cheat Sheet

Let's discuss the key points to focus on while designing a RESTful API.

REST (REpresentational State Transfer) has no standards but there are some data points to keep in mind while designing the URLs.

Why it is called REST? It is called as Representation State Transfer as the response data format (XML or JSON) can be interchanged based on client-server agreement which happens via HTTP Request and Response Header field Content Type.

URI Designing Guidelines

The URIs should be resource based & not action based

Action based - /getmessages.do?user=1

Resource based - /messages/1

Identify the entities (resources) in the system and create unique URIs for them. The URIs should have plural form of entities (nouns) & not verbs i.e.

No singular noun - /message/1

No verb - /getmessage/1

Plural noun - /messages/1

Designing Collection URIs

To get a collection of resources in response, the URI will be

To get all messages - /messages


Designing URIs around resource relations

To get all comments of message with id 1 - /messages/1/comments

To get comment with id 2 for message with id 1 - /messages/1/comments/2


Filtering criteria should be passed as query parameter (query string)

To get all the messages for the year 2014, with pagination (start at 30 and 10 records at a time) -
/messages?year=2014&offset=30&limit=10

Using HTTP Methods

As we have identified designing instance and collection URIs, next let's look at the operations that can be performed and data that's exchanged.

The following table brings in a bright comparison between non-RESTful and RESTful URLs.

Non-REST	RESTful
URL	URL	HTTP Method
/getMessages.do?id=1	/messages/1	GET
/postMessges/do?id=1	/messages/1	POST
/updateMessages.do?id=1	/messages/1	PUT
/deleteMessages.do?id=1	/messages/1	DELETE

Delete comment with id = 2 for message with id = 1
HTTP Method: DELETE
URL: /messages/1/comments/2 

Delete all comments for message with id = 1 (used seldom)
HTTP Method: DELETE
URL: /messages/1/comments

Update all comments for message with id = 2 with a list of new comments (used seldom)
HTTP Method: PUT
URL: /messages/1/comments
Body: List of new comments

Add a new comment to message with id = 1
HTTP Method: POST
URL: /messages/1/comments
Body: Comment

Note - You can't create comments in bulk. For each comment in the body, you need to hit the URL.

Method Idempotence

There are two ways in which we can classify popular HTTP methods.

GET - Read Only
POST, PUT, DELETE - Write

or

GET, PUT, DELETE - Repeatable
POST - Non-repeatable

E.g. count = 6
If you execute the above statement 100 times, at the end the value of count will remain 6. Hence this is repeatable and safe.

Methods (GET, PUT, DELETE) which are safely repeatable are called Idempotent methods. Others (POST) are called non-Idempotent methods.

The advantage is that the client can safeguard itself from non-idempotent methods correctly. E.g. when you do refresh, browser simply hits the same last hit URL. When the method is GET, it goes ahead because it is safely repeatable. But when the method of last hit URL is POST, it asks for confirmation before proceeding with the request.

HTTP Status Codes

The status code and a description in response informs the client about what has happened to the request it has made to the server. The codes are from 100 to 599.

Not all the values in the range are used as code, which means there are not 500 different status codes.

The first digit of code represents a class. Hence there are 5 classes from 1 to 5.

Informational Codes - 1


This is used for acknowledgment. The codes in this class are not used in REST services.

Success Codes - 2


200 - OK
201 - Created
203 - Created and acknowledged (this is better than 201)
204 - No content to send. This is used in response to a DELETE request.

Redirection Codes - 3


These are used by server to do further action to complete it's request.

302 - Found
307 - Temporary Redirect

Any of the above codes are used by server to tell the client don't ask me & ask to another server.

304 - Tells client nothing has changed since last request

Client Error - 4


Status code from his class is sent when the client makes an error; the request syntax might be incorrect or the client is requesting for something which it is not intended to see.

400 - Bad Request
401 - Unauthorized (The client needs to sign in)
403 - Forbidden (though client is signed in but s/he is not having rights to view the resource requested)
404 - Not Found
415 - Unsupported Media Type - (client is speaking in some language which the server can't understand)

Server Error - 5


500 - Internal Server Error (Error details must be sent in the body of the response)

Following chart gives a comprehensive list of HTTP Request Methods and Response codes for respective scenarios.