REST API response format based on some of the best practices
1- GET - Get single item - HTTP Response Code: 200
HTTP/1.1 200
Content-Type: application/json
{
"success": true,
"data": {
"id": 10,
"name": "shirt",
"color": "red",
"price": "$23"
}
}2- GET - Get item list - HTTP Response Code: 200
HTTP/1.1 200
{
"success": true,
"count": 100,
"limit": 20,
"offset": 30,
"datas": [{
"id": 10,
"name": "shirt",
"color": "red",
"price": "$123"
},
{
"id": 11,
"name": "coat",
"color": "black",
"price": "$2300"
}
]
}3- POST - Create a new item - HTTP Response Code: 201
HTTP/1.1 201
Location: /v1/items/12
Content-Type: application/json
{
"success": true,
"data": {
"id": 10,
"name": "shirt",
"color": "red",
"price": "$23"
}
}4- PATCH - Update an item - HTTP Response Code: 200/204
The same response with create a new item
HTTP/1.1 200If updated entity is not to be sent after the update
HTTP/1.1 2045- DELETE - Delete an item - HTTP Response Code: 204
HTTP/1.1 2041- GET - HTTP Response Code: 404
HTTP/1.1 404
Content-Type: application/json
{
"success": false,
"message": "The item does not exist"
}2- DELETE - HTTP Response Code: 404
HTTP/1.1 404
Content-Type: application/json
{
"success": false,
"message": "The item does not exist"
}3- POST - HTTP Response Code: 400
HTTP/1.1 400
Content-Type: application/json
{
"success": false,
"message": "Validation errors in your request", /* skip or optional error message */
"errors": [
{
"message": "Oops! The value is invalid",
"code": 34,
"field": "email"
},
{
"message": "Oops! The format is not correct",
"code": 35,
"field": "phoneNumber"
}
]
}4- PATCH - HTTP Response Code: 400/404
HTTP/1.1 400
Content-Type: application/json
// THE SAME WITH POST
HTTP/1.1 404
Content-Type: application/json
{
"success" : false,
"message": "The item does not exist"
}5- VERB Unauthorized - HTTP Response Code: 401
HTTP/1.1 401
Content-Type: application/json
{
"success" : false,
"message": "Authentication credentials were missing or incorrect"
}6- VERB Forbidden - HTTP Response Code: 403
HTTP/1.1 403
Content-Type: application/json
{
"success" : false,
"message": "The request is understood, but it has been refused or access is not allowed"
}7- VERB Conflict - HTTP Response Code: 409
HTTP/1.1 409
Content-Type: application/json
{
"success" : false,
"message": "Any message which should help the user to resolve the conflict"
}8- VERB Too Many Requests - HTTP Response Code: 429
HTTP/1.1 429
Content-Type: application/json
{
"success" : false,
"message": "The request cannot be served due to the rate limit having been exhausted for the resource"
}9- VERB Internal Server Error - HTTP Response Code: 500
HTTP/1.1 500
Content-Type: application/json
{
"success" : false,
"message": "Something is broken"
}10- VERB Service Unavailable - HTTP Response Code: 503
HTTP/1.1 503
Content-Type: application/json
{
"success" : false,
"message": "The server is up, but overloaded with requests. Try again later!"
}Validation error formats can be different depending on your requirements. Following are some other popular formats, other than the one used above.
HTTP/1.1 400
Content-Type: application/json
{
"success": false,
"message": "Validation errors in your request", /* skip or optional error message */
"errors": [
{
"message": "Oops! The value is invalid",
"code": 34,
"field": "email"
},
{
"message": "Oops! The format is not correct",
"code": 35,
"field": "phoneNumber"
}
]
}PATCH with partial json can be used for updating the resource: https://tools.ietf.org/html/rfc7396
Avoid using 'X-' in custom headers: https://tools.ietf.org/html/rfc6648
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent