Each microservice's API should return the data in the same way, defined below:
- The API should be RESTful (see here about the REST)
- The API should return the data in the format according to the 'Accept' request header. Use JSON (MIME type'application/json') when either the header is not set, or when the other formats aren't available. (Example: return XML if the 'Accept' header is 'application/xml', return CSV if the 'Accept' header is 'text/csv' etc.)
- The API should return the standard HTTP response codes depending on the result. (Example: return '200 OK' after the objects listing, return '201 Created' after the object creation, return '404 Not Found' if the object was not found etc.)
- The API should act accordingly to the request method (e.g. GET gets something, PUT creates something, etc).
- The JSON response should have the same structure (see below).
Response structure
Each response should have the same structure, depending on the request and the result.
The response structures for the successful and unsuccessful request are slightly different.
Successful response
{
"success": true,
"meta": {},
"data": [],
"message": "A message to user."
}
- success - Mandatory field. A boolean that represents if the API call was successful or not. Should always be true for the successful call.
- meta - Optional field. An object containing meta information, if any. (e.g. pagination data, timestamps etc.)
- data - Optional field. An array containing 1 or more object requested/modified/deleted by user.
- message - Optional field. A string containing a message to the user, useful on POST/PUT/DELETE requests.
In the response, either the 'data' or 'message' fields should be presented.
Unsuccessful response
{
"success": false,
"errors": [],
"message": "An error has occured."
}
- success - Mandatory field. A boolean that represents if the API call was successful or not. Should always be false for the unsuccessful call.
- errors - Optional field. An array containing errors' details, if available. (e.g. validation errors)
- message - Mandatory field. A string containing an error message.