Writing REST APIs – CRUD – Request & Response – Best Practices – Part I

Writing REST APIs - CRUD - Request & Response - Part I

Writing REST APIs – CRUD – Request & Response – Best Practices – Part I

I am going to publish a series of posts  related to REST APIs standards and today we will see some details on designing the request and response for an API. So now we will assume we are going to write an API for user managements and we call this User API. When writing an API, the following are the 5 basic endpoint required to supports most of the common use-cases.

  1. POST – Create one or more users
  2. PATCH – Update one user by given ID
  3. PATCH – Update one or more users by given ID’s
  4. GET – Get user by given ID
  5. GET – Get all users
  6. DELETE – Delete user by given ID

No we will see in detail about the request and response structure.


1 . POST – Create one or more users

Request :

POST /users
{
     "users" : [{
          "firstName" : "Tom",
          "lastName" : "Cruise"
     },{
          "firstName" : "Tom",
          "lastName" : "Hardy"
     }]
}

Response 1 :

{
     "statusCode" : 201,
     "statusDescr" : "Created"
     "details" : [{
          "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx",
          "statusCode" : 201,
          "statusDescr" : "Created"
     },{
          "id" : "yyyyyyyyyyyyyyyyyyyyyyyyy",
          "statusCode" : 201,
          "statusDescr" : "Created"
     }]
}

Response 2 :

If you notice in the below response, we have different responses and so we have the global response to be 207 (Multi-Status) HTTP status code.

{
     "statusCode" : 207,
     "statusDescr" : "Multi-Status"
     "details" : [{
          "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx",
          "statusCode" : 201,
          "statusDescr" : "Created"
     },{
          "id" : "yyyyyyyyyyyyyyyyyyyyyyyyy",
          "statusCode" : 201,
          "statusDescr" : "Conflict"
     }]
}

2. PATCH – Update one user by given ID

Request :

PATCH /users/xxxxxxxxxxxxxxxxxxxxxxxxx
{
     "firstName":"Tom"
}

Response 1 : 

HTTP Response 200
No response body for successful update

Response 2 : Error Case

{
     "statusCode" : 400,
     "statusDescr" : "PATCH not supported on the field firstName"
}

3. PATCH – Update one or more users by given ID’s

Request :

PATCH /users
{
     "users" : [{
          "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx"
          "firstName" : "John",
     },{
          "id" : "yyyyyyyyyyyyyyyyyyyyyyyyy"
          "firstName" : "Sam",
     }]
}

Response 1 :

{
     "statusCode" : 200,
     "statusDescr" : "OK"
     "details" : [{
          "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx",
          "statusCode" : 200,
          "statusDescr" : "OK"
     },{
          "id" : "yyyyyyyyyyyyyyyyyyyyyyyyy",
          "statusCode" : 200,
          "statusDescr" : "OK"
     }]
}

Response 2 :

If you notice in the below response, we have different responses and so we have the global response to be 207 (Multi-Status) HTTP status code.

{
     "statusCode" : 207,
     "statusDescr" : "Multi-Status"
     "details" : [{
          "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx",
          "statusCode" : 200,
          "statusDescr" : "OK"
     },{
          "id" : "yyyyyyyyyyyyyyyyyyyyyyyyy",
          "statusCode" : 400,
          "statusDescr" : "PATCH not supported on the field firstName"
     }]
}

4. GET – Access user by given ID

Request :

GET /users/xxxxxxxxxxxxxxxxxxxxxxxxx

Response 1 :

{
     "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx"
     "firstName" : "Tom",
     "lastName" : "Cruise"
}

Response 2 :  Error Case

{
     "statusCode" : 404,
     "statusDescr" : "Not Found"
}

5. GET – Get all users

Request :

GET /users

Response 1 :

{
     "users" :[{     
          "id" : "xxxxxxxxxxxxxxxxxxxxxxxxx"
          "firstName" : "Tom",
          "lastName" : "Clancy"
     },{     
          "id" : "yyyyyyyyyyyyyyyyyyyyyyyyy"
          "firstName" : "Tom",
          "lastName" : "Cruise"
     }]
}

Response 2 :

{
     "users" :[]
}

6. DELETE – Delete user by given ID

Request :

DELETE /users/xxxxxxxxxxxxxxxxxxxxxxxxx

Response 1 :

HTTP Response 200
No response body for successful update

Response 2 : Error Case

{
     "statusCode" : 404,
     "statusDescr" : "Not Found"
}

PUT is similar to PATCH operation except that PUT should be used to update (full update) the given resource/user, where as PATCH is used for partial update. The request and response structure remain similar for PATCH and PUT.

Related Links:

  1. Writing REST APIs - CRUD - Request & Response - Best Practices - Part I
  2. Writing REST APIs - CREATE/POST - Best Practices – Part II
Read More...

[ YOU MAY ALSO LIKE ]

Leave a Reply