I have a HTTP JSON API, which runs on php, on a small framework. This API is a wrapper for a databases pgsql functions. Php framework returns responses in such way:
{
code: 200,
data: []
}
Codes are HTTP code responses (such as 200, 301, 302, etc). pgsql functions returns their own code (negative values for errors, positive for success results), message (meaning of code) and result data:
{
code: -1,
message: 'Wrong data',
data: []
}
So, my packages from API are:
{
code: 200,
data: {
code: 1
message: 'Succeed'
data: []
}
}
Isn't it messy? Occur some confusions when writing client code, that requests this API. Maybe there are some standard patterns for making some kind of packages of API.
Your API layout is not messy. As Botond suggested, it is actually pretty logical. The only change I would make to it would be to move your status codes into HTTP headers rather than in the JSON data, to reduce the format a bit. This will also allow you to easily differentiate between successful calls and errors.
Suppose your API can answer with 4 different codes: 200, 201, 403, 404. Respectively: done, not changed, forbidden, not found. Instead of passing this as a JSON variable, you could easily bind it into the HTTP response header, as the values already exist and are well understood. This, as in this question, is a pretty well-accepted method of providing status codes, provided that you are not using this specific header for anything else.
See you have to read the responses in Iterative manner. You can read the JSON response and then check if the data field has another object/array.
You have to assess the code and show error messages on all codes except 200.