
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.
Leave a Reply