@@ -0,0 +1,252 @@
# rest-api-response-format
REST API response format based on some of the best practices
## Rest API Popular Endpoint Formats
> https://api.example.com/v1/items
> https://example.com/api/v1/items
## Rest API Success Responses
1- GET - Get single item - HTTP Response Code: ** 200**
``` javascript
HTTP / 1.1 200
Content- Type: application/ json
{
" id" : 10 ,
" name" : " shirt"
" color" : " red"
" price" : " $23"
}
```
2- GET - Get item list - HTTP Response Code: ** 200**
``` javascript
HTTP / 1.1 200
Pagination- Count: 100
Pagination- Page: 5
Pagination- Limit: 20
Content- Type: application/ json
[
{
" 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**
``` javascript
HTTP / 1.1 201
Location : / v1/ i tems/ 12
Content- Type: application/ json
{
" message" : " The item was created successfully"
}
```
4- PATCH - Update an item - HTTP Response Code: ** 200/204**
> If updated entity is to be sent after the update
``` javascript
HTTP / 1.1 200
Content- Type: application/ json
{
" id" : 10 ,
" name" : " shirt"
" color" : " red"
" price" : " $23"
}
```
> If updated entity is not to be sent after the update
``` javascript
HTTP / 1.1 204
```
5- DELETE - Delete an item - HTTP Response Code: ** 204**
``` javascript
HTTP / 1.1 204
```
## Rest API Error Responses
1- GET - HTTP Response Code: ** 404**
``` javascript
HTTP / 1.1 404
Content- Type: application/ json
{
" message" : " The item does not exist"
}
```
2- DELETE - HTTP Response Code: ** 404**
``` javascript
HTTP / 1.1 404
Content- Type: application/ json
{
" message" : " The item does not exist"
}
```
3- POST - HTTP Response Code: ** 400**
``` javascript
HTTP / 1.1 400
Content- Type: application/ json
{
" 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**
``` javascript
HTTP / 1.1 400
Content- Type: application/ json
{
" message" : " Validation errors in your request" /* skip or optional error message */
" errors" : [
{
" message" : " Oops! The format is not correct"
" code" : 35 ,
" field" : " phoneNumber"
}
]
}
HTTP / 1.1 404
Content- Type: application/ json
{
" message" : " The item does not exist"
}
```
5- VERB Unauthorized - HTTP Response Code: ** 401**
``` javascript
HTTP / 1.1 401
Content- Type: application/ json
{
" message" : " Authentication credentials were missing or incorrect"
}
```
6- VERB Forbidden - HTTP Response Code: ** 403**
``` javascript
HTTP / 1.1 403
Content- Type: application/ json
{
" message" : " The request is understood, but it has been refused or access is not allowed"
}
```
7- VERB Conflict - HTTP Response Code: ** 409**
``` javascript
HTTP / 1.1 409
Content- Type: application/ json
{
" message" : " Any message which should help the user to resolve the conflict"
}
```
8- VERB Too Many Requests - HTTP Response Code: ** 429**
``` javascript
HTTP / 1.1 429
Content- Type: application/ json
{
" 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**
``` javascript
HTTP / 1.1 500
Content- Type: application/ json
{
" message" : " Something is broken"
}
```
10- VERB Service Unavailable - HTTP Response Code: ** 503**
``` javascript
HTTP / 1.1 503
Content- Type: application/ json
{
" message" : " The server is up, but overloaded with requests. Try again later!"
}
```
## Validation Error Formats
Validation error formats can be different depending on your requirements. Following are some other popular formats, other than the one used above.
``` javascript
HTTP / 1.1 400
Content- Type: application/ json
{
" message" : " Validation errors in your request" /* skip or optional error message */
" errors" : {
" email" : [
" Oops! The email is invalid"
],
" phoneNumber" : [
" Oops! The phone number format is not correct"
]
}
}
```
``` javascript
HTTP / 1.1 400
Content- Type: application/ json
{
" message" : " Validation errors in your request" /* skip or optional error message */
" errors" : {
" email" : [
{
" message" : " Oops! The email is invalid"
" code" : 35
}
],
" phoneNumber" : [
{
" message" : " Oops! The phone number format is not correct"
" code" : 36
}
]
}
}
```
## References
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
Igor J. Santos revised this gist
Igor J. Santos
revised
this gist