Requesting, headers and encoding (and version)

Most endpoints support both GET and POST. Parameters may be passed as query-string parameters, as form-encoded POST data, or as a JSON body (with Content-Type: application/json); the three forms are equivalent, and a few endpoints whose parameters are lists — this is then documented — require the JSON body form.

You may specify the encoding the API should use to return data through standard HTTP content negotiation.

The header to use is "Accept" and must contain a version information.

Accept: application/json;version=0

(version must be present, but is usually reserved for the future, therefore, some endpoints like SMS functions require another value, in that case, this is documented)

Available encoders are:

The reply envelope

Whatever the encoding, successful replies share a common envelope: the endpoint-specific data is accompanied by a few common fields — code (the HTTP status, repeated in the body), diagnostic (a short human-readable outcome, "Success" on success), stamp (the server time of the reply), url (the requested URL) and version (the API version used to answer). Errors use the same envelope, with the appropriate code and a diagnostic explaining what went wrong.

Here is an example of a query with good headers:

% curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN'

{
 "api_call_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "api_key": "KKKK",
 "code": 200,
 "diagnostic": "Success",
 "mode": "normal",
 "stamp": "2018-02-06 10:10",
 "url": "https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN",
 "version": 0
}