REST API response format based on some of the best practices

rest-api-response-format.md

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

    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

    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

    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

    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

    HTTP/1.1  204

5- DELETE - Delete an item - HTTP Response Code: 204

    HTTP/1.1  204

Rest API Error Responses

1- GET - HTTP Response Code: 404

    HTTP/1.1  404
    Content-Type: application/json
 
    {
      "message": "The item does not exist"
    }

2- DELETE - HTTP Response Code: 404

    HTTP/1.1  404
    Content-Type: application/json
 
    {
      "message": "The item does not exist"
    }

3- POST - HTTP Response Code: 400

    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

    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

    HTTP/1.1  401
    Content-Type: application/json
 
    {
      "message": "Authentication credentials were missing or incorrect"
    }

6- VERB Forbidden - HTTP Response Code: 403

    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

    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

    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

    HTTP/1.1  500
    Content-Type: application/json
 
    {
      "message": "Something is broken"
    }

10- VERB Service Unavailable - HTTP Response Code: 503

    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.

    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"
                ]
        }
    }

    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

great content

Thanks!

what if , when there is reference fields,

for example in posts table
posts

• id
• user_id
• name

GET REQUEST: /api/posts/1
response is
{
id:1,
user_id:1,
name:"post1"
}

but i want detail of user too

should the response be
response is
{
id:1,
user_id:{
...user details
}
name:"post1"
}

or

response is
{
id:1,
user:{
....user details.
}
name:"post1"
}

response for nested fields

@sagartmg2 it's better to use like this:

{
  id: 1,
  user: {
    id: 2,
    name: "Jon"
    // other user details here...
  },
  name: "post1"
}

What should I do if I need response a message for case 200 beside data? Example POST response 200 with data inserted and a message to remind user execute next step.

What should I do if I need response a message for case 200 beside data? Example POST response 200 with data inserted and a message to remind user execute next step.

I couldn't understand what exactly is the problem you're trying to solve.
But this guide is just a reference/starting point. You can adapt the HTTP Response codes to fit your needs.

There's a wide range of codes you could use.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status