https://github.com/adnan-kamili/rest-api-response-format
REST API response format using HTTP status codes
https://github.com/adnan-kamili/rest-api-response-format
rest rest-api restapi restful
Last synced: 12 months ago
JSON representation
REST API response format using HTTP status codes
- Host: GitHub
- URL: https://github.com/adnan-kamili/rest-api-response-format
- Owner: adnan-kamili
- License: mit
- Created: 2016-07-28T12:20:55.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2017-08-30T11:15:45.000Z (almost 9 years ago)
- Last Synced: 2025-06-24T14:13:46.273Z (12 months ago)
- Topics: rest, rest-api, restapi, restful
- Homepage:
- Size: 14.6 KB
- Stars: 501
- Watchers: 14
- Forks: 118
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# rest-api-response-format
REST API response format based on some of the best practices
The **swagger.yaml** file for following sample responses is available at:
https://github.com/adnan-kamili/swagger-sample-template
## 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/items/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