Most of the time as a developer we only take care about the coding standards, do not follow the API designing standards. we should consider both coding standard as well as API designing best practices.

Below are the 10 points which we should follow when designing the Restful API.

1. Use API Version

Use the API versions do not delete the old API, if there is any major changes or changes
in input and output in the API do not do the changes in the same version.
create a new versions so that existing applications will work.

Do not use floating point numbers like 3.2, use integers.

Example

GET /v1/users
GET /v2/users/questions

2. Resource name should use nouns, no verbs.

The uri should use the nouns , it should not use the verbs

Examples

GET

Get the details of user with id 21

Good Endpoint – GET /users/21

Bad Endpoint – GET /getUserDetails?id=21

Get the details of all users

Good Endpoint – GET /users
Bad Endpoint – GET /getAllUserDetails

POST

Create new user

Good Endpoint – POST /users

Bad Endpoint –  POST /createNewUsers

PUT

Update all user details

Good Endpoint –  PUT   /users

Bad Endpoint – PUT   /updateAllUsers

Bad Endpoint – POST  /updateAllUsers

Update a user details with user id 21

Good Endpoint – PUT /users/21

Bad Endpoint – PUT /updateUsers?id=21

DELETE

Delete all users

Good Endpoint – DELETE /users

Bad Endpoint – DELETE /allUsers

Delete a user with id 21

Good Endpoint – DELETE /users/21
Bad Endpoint – DELETE /userdetils?id=21

3. GET method should not edit/create/delete data

GET method is used to fetch/query the data, it should not be use to create, change or delete the data.

POST –

Create new records

PUT –

Update the existing records

DELETE –

Delete the records

4. Use plural form of nouns

Do not use singular form of nouns , always use the plural forms .

example

Get details of user whose id is 21

Good Endpoint – GET /users/21

Bad Endpoint – GET /user/21

Whether it is single user or multiple user we should use the plural forms.

5. Show relations with sub resource

Sub resource should be used to show the relations

Example

Get all the questions posted by user 21

Good Endpoint- GET /users/21/questions

Bad Endpoint- GET/getAllQuestions?userId=21

6. Use same HTTP headers for serialization formats

Both client and server should use the same format for communications.
It should specify the consume and produce content-type. Basically it should use the common
content-type that JSON, it is easy to use.

7. Use HATEOAS

HATEOAS-

Hypermedia as the Engine of Application State. see more details here
Hypermedia links should be used to navigate through the API,

question details
{
“id”: 91,
“questions”: “what is JVM”,
“answers”: 5,
“type”: 2,
“date”:”19/06/15″,
“users”:
{
“id”: “2”,
“name”: “Nirmal Dhara”,
“links”:
{
“rel”: “self”,
“href”: “/javamad/v1/users/2”
}
}
}

8. Provide filtering, paging, and sorting, for results

Filtering:

Use all the fields as query parameter for filtering.

Example

GET /users?exp=5

 It returns a user list with experience 5 years
GET /users?exp=5 & lan=java

It returns a list of users with 5 years experience in java
GET /users?exp=5 & lan=java & location=bangalore

It returns list of java developers having 5 years of experience and curent location is bangalore

Sorting:

Allow ascending and descending order sorting for all the fields.

Example

Get all the user with ascending order of start date

GET/users/sort=startdate asc

Get all the users with descending order of experience

GET /users/sort=exp dec

Paging

Returns all the data is not a good idea. some times it is not required and it takes more time to fetch also.
Use limit and offset to return data page by page.

Example

Return 10 users per page(number of records per page depends upon the requirements)

GET /users/offset=1&limit=10                             – it will return user 1 to 10
GET /users/offset=11&limit=10                           – it will return user 11 to 20
GET /users/offset=21&limit=10                          – it will return user 21 to 30

9. Return error details with proper HTTP status codes

do not return the simple error code and message, it is really hard for user to understand.
Many developers do the exceptions handling properly but do not return the proper HTTP code.
They catch the exceptions and return error code 500 and message as “internal server error”,
return proper HTTP code as REST is build over HTTP.

HTTP Status Codes

1. 1xx – Informational

2. 2xx – Success

3. 3xx – Redirection

4. 4xx – Client Error

5. 5xx – Server Error

For more details please see here

10. Documentation

Create a good word documents which can be used by developers and testers, as documents is only way to access the API . Use framework like Swagger(more details here) to sync the documents automatically. WADL can be useful for client developers.