REST API response format for Modern Day Single Page and Mobile Apps

After building a lot of REST APIs in the last 6 years, I have finally converged on one single signature for all my responses.

There are 6 keys that I send in every response.

Data, Status Message and Status Code

These three keys are simple and straightforward.

Data contains any data that you want to send back to the user, in case of a successful response.

Status Message is the is a message for the front-end developer as a one line summary about the request processed for eg. “Post created successfully”.

Status Code is an integer HTTP response, in the above case it would be 201.

Update

This has been a life saver for us in a lot of cases. This variable is mostly false, It is only true when we want client to either update the app or we want to refresh the code of our single page application.

While parsing every response at client side we check if this variable is true or false, if it is true, we won’t be using the current client side code and either we need to update app or refresh the browser.

We use this while patching security updates or some critical changes for which we are not able to provide backward compatibility.

How we handle this variable at the back-end ?

With every request from client, we require the client to send two things client_version_number and client_platform.

While parsing every request, we check client version number and client platform. For every client platform we maintain a minimum number that we support. Like with our new release, the minimum number we support is 44 for web platform. We’ll simple start sending update true for client_version_number < 44.

The client will detect update true and will ask the user to do refresh the browser, generally giving a button on a popup.

Disabled

What if a user is misusing the app or exploiting the server resources ? We want to disable that user right ?

The way we do this is by maintaining a flag named disabled which is false by default with every user. As soon as we encounter any suspicious activity we mark this variable as true.

At the client side, when disabled true is received we simply show that your user has been disabled please contact the administrator.

Error

The last of them, this is generally an array of messages, to tell either the developer or the user about what went wrong. Any back-end validation that is not client side will come through this. Or any server failure.

Data key and error key are larger areas of discussion as how to structure them, I’ll write another blog for these two keys.