API responses

The Chimpy POS API is a RESTful API that responds in JSON format.

Responses

After receiving and interpreting a request message, the server responds with an HTTP response message containing a status code (check RFC 2616 for more information) and a response body containing relevant JSON data.

If everything works correctly (HTTP 200 OK), the response body will contain a main data key to wrap the business logic information.
Eventually, if there is a client error (HTTP 400 Bad Request), the response body will contain a main error key to wrap the error information.

Note

Even if a request is carried out successfully (response status: HTTP 200 OK), a business logic error can be returned within the JSON response body. For instance, when a battery cannot be picked up or returned at that moment or when a user's account is not active.

HTTP 200 - Response structure

{ "data": { <resource>: { "status": <success_enum_string or "error">, "error_type": <error_enum_string or null>, "error_message": <error_message_string_in_locale or null>, "relevant_data_key_x": <relevant_data_value_x>, ... } }, "locale": <locale>, "req": <request_object> }

Business logic success

A business logic success (e.g. "This battery can be rented out!"), will respect the following conditions:

status is not error
both error_type and error_message are null

Business logic error

A business logic error (e.g. "This battery has already been returned."), will respect the following conditions:

status is error
both error_type and error_message are not null

Business logic error types

The following list gives an exhaustive list of possible error_types. Associated error_message is a string in the requested language (param lang) that can be overwritten by the terminal software.

battery_non_existing: A battery with this identifier doesn't exist.
battery_already_used: The battery with this identifier has already been rented out, therefore it cannot be picked up again.
battery_not_rented_out: The battery with this identifier has not been rented out yet, therefore it cannot be returned.
battery_already_returned:The battery with this identifier has already been returned, therefore it cannot be returned again.
coupon_invalid: the applied user coupon is not valid
battery_expired: the battery with this identifier has expired, therefore it cannot be returned.
undefined: An undefined error has occurred.

HTTP 400 - Response structure

When a client error occurs, the following response structure will be applied:

{ "error": { "type": <error_enum_string>, "message": <error_message_string_in_locale> } }, "locale": <locale>, "req": <request_object> }

Last updated on