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.
2. Resource name should use nouns, no verbs.
The uri should use the nouns , it should not use the verbs
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
Create new user
Good Endpoint – POST /users
Bad Endpoint – POST /createNewUsers
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 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.
Create new records
Update the existing records
Delete the records
4. Use plural form of nouns
Do not use singular form of nouns , always use the plural forms .
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
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
Hypermedia as the Engine of Application State. see more details here
Hypermedia links should be used to navigate through the API,
“questions”: “what is JVM”,
“name”: “Nirmal Dhara”,
8. Provide filtering, paging, and sorting, for results
Use all the fields as query parameter for filtering.
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
Allow ascending and descending order sorting for all the fields.
Get all the user with ascending order of start date
Get all the users with descending order of experience
GET /users/sort=exp dec
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.
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
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.