Page: common response
2019-12-08 01:12
Common response
As is mentioned in common request, the API request is JSON-encoded GET or POST request, which response is always 200 OK
with a payload carrying information on the command execution. The only reason of receiving non-200 code is a severe, hard error, like bad path path (404), wrong request format or internal server error what normally is not happening.
All other errors, soft errors, are returned with status 200 OK with error data encoded in a standard way with all necessary data, see error response below. We do not rely on HTTP status codes as there are too many different situations that can not be covered by these status codes only. Instead, we introduce error code which resolves any ambiguity concerning errors.
To distinguish success and error responses, client checks the response data which is:
{ status: "OK" | "error" }
the status
field always exists and has either OK
or error
value.
Success response
The response busy has the following form:
{ status: "OK", <payload> }
The payload can be empty or contain any command-specific returned data. Keys can be any values except the state
. The standard way of carrying data about come object is either:
{ status: "OK",
SomeType: {
id: number,
field1: value1,...
}
}
for single objects of type SomeType
and
{ status: "OK",
SomeTypes:[
{
id: number,
field1: value1,...
}
}
For an array of typed objects.
Notice the id
field that is often used to identify objects and is a long number (1...2^63 range).
Error response
has two more predefined keys that always exist and can not be used by the API payload:
{ status: "error", code: "some_error_code", text: "error_text", <payload> }
code
: error code,one_word_identifier
describing the error typeerror_text
: human readable error description, that could be shown to the end user. It could be I18n'ed using the request headers in a usual way. Otherwise, the client software should provide localised message itself using the code.
payload
can carry any additional specific error information, but generally API should try to avoid any extra data in the error response.