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 type
• error_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.