Add REST API response format documentation based on best practices

2026-07-17 22:10:48 +07:00 · 2026-07-17 22:10:48 +07:00 · 74253f0d4a
commit 74253f0d4a
parent 3393170fe5
1 changed files with 250 additions and 0 deletions
--- a/REST_API_RESPONSE_FORMAT.md
+++ b/REST_API_RESPONSE_FORMAT.md
@ -0,0 +1,250 @@
+# 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/items/12
+    Content-Type: application/json
+ 
+    {
+      "message": "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: **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- PUT -  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
+Avoid using 'X-' in custom headers: https://tools.ietf.org/html/rfc6648