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 200
If updated entity is not to be sent after the update
HTTP/1.1 204
5- DELETE - Delete an item - HTTP Response Code: 204
HTTP/1.1 204
1- 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