I have 6 endpoints that return 6 json response:
/cities/{id}return a json object: {
“city”: “Orlando”,
“altitude”: 10
}/citiesreturn an array: [{
“city”: “Orlando”,
“altitude”: 70},
{“city”: “New York”,
“altitude”: 5}]
the other 4 endpoint are of the same kind (single object and array) but return totally different object/s.
Now I want to change the response payload, and envelope it in another object to add an hash of the original response and other info about the request that the user made. So for example, for the 2 endpoint above, I can have this:
{
"uuid": "38271b3f-a097-43a6-82e9-ca482358a811",
"date": "2024-09-10T15:25:04.771+02:00",
"hash": -313570381,
"data": {
"city": "Orlando",
"altitude": 10
}
}
or
{
"uuid": "38271b3f-a097-43a6-82e9-ca482358a811",
"date": "2024-09-10T15:25:04.771+02:00",
"hash": -313570381,
"data": [{
"city": "Orlando",
"altitude": 70},
{"city": "New York",
"altitude": 5}]
}
or if I had an error, for example I will return 404 and a message:
{
"uuid": "38271b3f-a097-43a6-82e9-ca482358a811",
"date": "2024-09-10T15:25:04.771+02:00",
"hash": -313570381,
"data": {
"errorMessage": "City not found"
}
}
The main question is if it is ok that the field data could contain so different information (I made the example for 2 endpoints, but I have 6 of them that returns different objects or array).
The optional side question, maybe too broad, if my design is good and how I can improve it.
11
The main point I would call out is the change of type of the data element dependent on whether an error occurred. In the case of a valid response you get a list of maps:
"data": [{
In the case of an error you get a map:
"data": {
Technically you CAN get away with this, since you have different HTTP return codes (200 for normal and 4xx for errors) so you know before you try to pass the body what the structure of the data block is. This is consistent with a definition language like OpenAPI, since it allows totally different response bodies based on the HTTP return codes.
That said I would probably add a bit more standardization to my API’s and have three (optional) top level keys:
result– a map representing a single result.results– a list of maps representing a list of result.errors– a list of maps representing a list of error objects.
In most cases exactly one of those keys will be present in the response.
Note: I wouldn’t bother with an error key, since its fine to return a list with one error in it. Error handling is likely to be fairly standardized, where as you don’t want to have to keep stripping off an outer list from API calls that will always return one result.
Ideally all fields should be as consistent as possible, in terms of their data format and their purpose.
You have two different core types of response purpose, a successful result and an error. Rather than overloading the same field with the payload of both, it might be a good idea to have a separate ‘result’ and ‘error’ field, mutually exclusive — either ‘result’ or ‘error’ must be present, but never both or neither.
In terms of the ‘result’ field, you can standardise this by always returning an array, even when the request is guaranteed to only give one record. Thus, /cities returns a ‘result’ array of zero or more records, while /cities/{id} returns a ‘result’ array of zero or one records but never more than one. (I’m assuming here empty results with zero records are valid, and not treated as an error condition.)
You then just write your handler code to assume every result is an array, so you don’t need separate code paths to handle the returns from different types of request.
javakx is a new contributor to this site. Take care in asking for clarification, commenting, and answering.
Check out our Code of Conduct.