REST API Standard

# REST API Standard REST API response format based on some of the best practices ## 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 Link: <http://localhost:9999/v1/destinations/all/1>; rel="prev",<http://localhost:9999/v1/destinations/all/2>; rel="next",<http://localhost:9999/v1/destinations/all/3>; rel="last" Content-Type: application/json { "data": [ { "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 // No body // The item was created successfully ``` 4- PUT - 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: **200** ```javascript HTTP/1.1 200 ``` ## Rest API Error Responses 1- VERB Unauthorized - HTTP Response Code: **401** ```javascript HTTP/1.1 401 Content-Type: application/json X-Response-Message: Text message//Message error // No body // Authentication credentials were missing or incorrect ``` 2- VERB Forbidden - HTTP Response Code: **403** ```javascript HTTP/1.1 403 Content-Type: application/json X-Response-Message: Text message//Message error // No body // The request is understood, but it has been refused or access is not allowed" ``` 3- No Found - HTTP Response Code: **404** ```javascript HTTP/1.1 404 Content-Type: application/json X-Response-Message: Text message//Message error // No body // The request is understood, but it has been refused or access is not allowed" ``` 4- VERB Conflict - HTTP Response Code: **409** ```javascript HTTP/1.1 409 Content-Type: application/json X-Response-Message: Text message//Message error // No body // Any message which should help the user to resolve the conflict ``` 5- VERB Too Many Requests - HTTP Response Code: **429** ```javascript HTTP/1.1 429 Content-Type: application/json X-Response-Message: Text message//Message error // No body // The request cannot be served due to the rate limit having been exhausted for the resource ``` 6- VERB Internal Server Error - HTTP Response Code: **500** ```javascript HTTP/1.1 500 Content-Type: application/json X-Response-Message: Text message//Message error // No body // Something is broken ``` 7- VERB Service Unavailable - HTTP Response Code: **503** ```javascript HTTP/1.1 503 Content-Type: application/json X-Response-Message: Text message//Message error // No body // 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 X-Response-Message: Text message//Message error // The object error is optional (ONLY POST, PUT, DELETE) { "errors": [ { "username": "Username is required" }, { "password": "Password is required" } ] } ``` ## 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