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.

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

JSON
    
 
{    "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>}
Copy

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:

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

Last updated on