Connection to API

Connection requirements

Interaction Model

The API uses the RESTful model (all the data is transferred as JSON objects). The feature of this model is that a partner and Koshelek use two interfaces for the interaction:

• Push API — used by the partner to send push messages.
• Callback API — used by Koshelek to transmit information on push messages delivery and reading by recipient to the partner.

Connection Parameters

API Requests Authorization

The HTTPS protocol is used. HTTP Basic Authentication (RFC 7617) mechanism should be used for API requests authorization. Credentials for authorization are transferred at the Authorization HTTP header.

Encoding Requirements

Both API requests and responses should use UTF-8 encoding.

Response Codes

If the request is successfully processed, the Koshelek host returns an HTTP response containing the status code 200, and the body with a payload described in the request documentation.

If an error occurred during the request processing, the host returns an HTTP response containing one of the status codes from the table below, and the error description as a JSON object in the body (the UTF-8 encoding is used):

Examples of error description:

{
    "status": "BAD_REQUEST",        // HTTP status of the error
    "errors": [                     // array of errors
        "msisdn: size must be between 0 and 10000", // error description
        "subId: may not be null"
    ]
}

{
    "status": "UNAUTHORIZED",
    "errors": [
        "Auth token is invalid"
    ]
}