Writing REST APIs – CREATE/POST – Best Practices – Part II

Writing REST APIs – CREATE/POST – Best Practices – Part II

This is my second post on Writing REST APIs. Today the focus is on POST HTTP method. Basically POST method is used for create a resource.

Sample Request :

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

Sample Response :

{
     "statusCode" : 201,
     "statusDescr" : "Created"
     "details" : [{
          "id" : "7995af4b-405e-48a2-960e-3d2f2918db0e",
          "statusCode" : 201,
          "statusDescr" : "Created"
     },{
          "id" : "e9768b26-097c-4b65-b1f5-dddcdc2790b4",
          "statusCode" : 201,
          "statusDescr" : "Created"
     }]
}

The id field in the response is UUID which will uniquely identify the created resource. We will be using this UUID to access this resource using PUT or GET. In each of the PUT or GET request, what we can do is that we can validate the id field to check whether the id is a valid UUID string.

  UUID.fromString("SAMPLE UUID");

The above snippet will throw Exception If we fail to pass a valid UUID. So what is the use? Let’s say we have created a resource in database which has id field with some valid UUID string. We will do a GET request with this id which is a valid case. Now we do a GET request with invalid id (some random id string). It is for sure that the resource will not be in the database since the id which we are using is not a valid UUID. So in this case we are doing an unnecessary DB call which we can reduce by validating id field. REST APIs are developed for it to be consumed by anyone including people (using any REST Client), web applications, real-time processors (may be Storm or Spark) etc. In few cases, there are possibilities for the REST APIs to be called with invalid id field and so it is better to validate the id field. In an application, we will have usecases where we will be using UUID in multiple places like accountId, userId, etc and we can validate these field from the request to avoid unnecessary database calls in invalid requests.

Default Fields/Attributes:

When we are creating a resource, it is better to have the following field stored in the database.

  • Created Date – Resource created date
  • Updated Date – Recently updated date of the resource
  • User ID – User ID of the person who recently updated the resource
  • Version – Version of the API with which we created the resource
  • Application ID

We will see a little more information on version field. Let’s say we have released User API for the first time and URL for it is /API/users/v1. After a few weeks/months we release a enhanced version of the API and the new URL is /API/users/v2. Note that we cannot update the existing version of the API unless it doesn’t break the consumers applications. In this case, the version field will store v1 or v2.

What is Application ID? REST APIs will be consumed by any application and these application will call the REST APIs using a  authentication token (used in HTTP header) with which we will be able to identify who is calling the REST API and this is how most of the REST APIs will be designed.  So Application ID will store the ID of the application which is the consuming the REST API.

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