When working in an environment with multiple development teams, each dedicated to developing or maintaining different parts of a company's product or systems, communication is one of the most common issues encountered.

To avoid adapting to different APIs depending on the application and to facilitate development, there are standards to define the format of responses such as JSend.

JSend is a response standard for communication between applications, based on a JSON with the following structure:

{
	"status": "SUCCESS",
	"data": {
		"user": {
			"username": "username",
			"email": "username@domain.com",
			...
		}
	}
}

Status

Represents the final state of the action, which can be:

• SUCCESS
  • The action required by the request has been completed successfully.
• FAIL
  • The preconditions for the required action have not been met.
  • Client error (HTTP 4xx).
• ERROR
  • An error occurred while processing the required action.
  • Server error (HTTP 5xx).

Data

Contains additional information about the result of the executed action. Its content may change depending on the status:

• SUCCESS

  • The content will be the resource that was requested to be retrieved or an empty object if the action had nothing to return:

    {
    	"status": "SUCCESS",
    	"data": {}
    }

• FAIL

  • It can be structured in various ways, but the important thing is to specify the precondition(s) that were not met, so the client can correct them.

  • Typically, a code is added to identify the error and a message providing more information. The fields can be declared as such or taken directly as a key-value object where the key is the code and the value is the description:

    // Structured version
    {
    	"status": "FAIL",
    	"data": {
    		"code": "InvalidEmailFormat",
    		"message": "Email address 'user@domain' has an invalid format"
    	}
    }
    // Key-value version
    {
    	"status": "FAIL",
    	"data": {
    		"InvalidEmailFormat": "Email address 'user@domain' has an invalid format"
    	}
    }

• ERROR

  • Although it can be structured similarly to FAIL, there is also the option to omit the data field and assume that, being a server error, it is unnecessary to specify beyond a descriptive message:

    // Version with "data" field
    {
    	"status": "ERROR",
    	"data": {
    		"code": "UnexpectedError",
    		"message": "Unexpected network error occurred"
    	}
    }
    // Simplified version
    {
    	"status": "ERROR",
    	"message": "Unexpected network error occurred"
    }

Considerations

There is no single way to do things, and each context is different, so before applying it, it is important to discuss it with others and bring it to team agreements, adapting it to the existing needs. For example, it might be considered redundant to specify error codes if the API to be consumed only manages a limited number of errors, allowing focus solely on the HTTP response code.

While it's good to have a standard, it's important not to lose sight of the fact that it's simply that, a starting point.