Simple API JSON Response Format

submited by

Style Pass

2021-09-04 07:00:05

The JavaScript Object Notation (JSON) format is a widely adopted standard to deliver HTTP RESTful API responses. This mostly because of the following properties:

Following a shared convention promotes reuse and helps increasing the productivity by leaving more time to focus on the actual development task. However, while there are many common patterns for structuring JSON-based HTTP/REST API responses, there is no consistency in things like naming or types of responses.

Several models have been proposed, but none has emerged as clear standard (e.g. JSend, JSON API, OData JSON Protocol, HAL, HATEOAS, etc…). Some models are quite simple, while others tends to be complex and over-prescribing. Amongst them the JSend format is probably the simplest one, defining only four top level fields (i.e. status, code, message and data). The simplicity of this model and its focus on application-level messaging are important features to promote adoption and reuse.

In addition to the fields defined by JSend, the model proposed here defines new mandatory fields that are particularly useful in modern distributed environments.