Skip to content

Making API calls

Jump to bottom
Martins Pilsetnieks edited this page Aug 16, 2017 · 6 revisions

Every API call is an HTTP request to a specific endpoint depending on the operation you want to do.

The structure of the request is that the URL will contain everything needed to determine the operation you want to make or data to retrieve, and the request body will contain any parameters necessary (if applicable). I.e., every operation (SMS or email sending, contact management, etc.) will have it's own URL.

The URL also contains the API version you want to use. Currently, the latest version (and the version specified in examples) is 2.0. The version number is incremented when any backwards-incompatible changes occur so you can still keep making calls to the version you've built your app against and they will be compatible

The basic URL structure is:

https://traffic.sales.lv/API:[VERSION]/[SECTION]:[OPERATION]
  • VERSION is API version number to maintain compatibility when changes to the API are made. If not specified, it defaults to the latest version (currently 2.0). (Note: changes to the API may be made without increasing the version number, if those changes don't break compatibility).
  • SECTION is the general part of the data you want to operate on, for example, Messaging, Email, Contacts, etc.
  • OPERATION is the name of the command you're issuing (for example, Send, Add, Delete - it depends on the section). Detailed descriptions are given in the relevant sections' pages.

So, an example request URL could be https://traffic.sales.lv/API:2.0/Messaging:Send

The response to any correct API request should be a JSON-encoded object. If you're using JSON, the easiest way to operate with that is to parse it into an associative array.

Request content

You should set a Content-Type header to indicate the format in which you'll be passing the data. Currently the options are either a JSON-encoded POST body (recommended,) or URL-encoded POST body, or a GET request with the parameters passed in the URL.

If you're passing the data as a JSON-encoded POST body (recommended) you should set the Content-Type to application/json. In this case a request could look like this:

POST /API:2.0/Messaging:NumberLookup/
Host: traffic.sales.lv
Authorization: Basic xxxx
Content-Type: application/json

{'Number': XXXXXXXXXXX}

You could also set the Content-Type to application/x-www-form-urlencoded and pass the data as an URL-encoded query string. In this case both POST and GET requests are possible, i.e., the two examples below are functionally identical:

POST /API:2.0/Messaging:NumberLookup/ HTTP/1.1
Host: traffic.sales.lv
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Content-Type: application/x-www-form-urlencoded

Number=XXXXXXXXXXX

--- and ---

GET /API:2.0/Messaging:NumberLookup/?Number=XXXXXXXXXXX HTTP/1.1
Host: traffic.sales.lv
Authorization: Basic dXNlcm5hbWU6YXBpa2V5

The system will default to the second approach if no content type is set, however, we do recommend using JSON for your requests as that will permit more complex data structures.

Request errors

The resulting data will differ for any successful request, however, unsuccessful requests will contain these elements:

  • Error with error number,
  • ErrorCode with a textual error code,
  • ErrorDescription with a human readable description of the error that has occurred.

Possible errors are listed here

Example of a returned error object

{
     'Error': 1,
     'ErrorCode': 'ERROR_KEY_UNAUTHORIZED',
     'ErrorDescription': 'The API key you provided was not found'
}

Authentication

To authenticate your requests you should use HTTP Basic authorization with your API account username as the username and the API key that is provided to you as the password.

You can authenticate by providing the authentication data in an "Authorize" header, for example:

Authorization: Basic base64("username":"key")

or by putting them inside the request URL, e.g.:

https://username:[email protected]/API:2.0/Messaging:Send/

In case of invalid authorization the response will have a "401 Unauthorized" status code, in addition to one of these errors:

  • ERROR_KEY_UNAUTHORIZED (1) if the username/API key you provided wasn't found at all
  • ERROR_IP_UNAUTHORIZED (2) if the API account isn't authorized to make API calls from the IP address you're using.

About date and time values

Everywhere where dates and times figure in this API, it is recommended to use ISO 8601 date and time formats, e.g., YYYY-MM-DD and the like. We do try to parse different date and time formats but with other formats some values might be too ambiguous.
In every place where dates and times are returned from Traffic, they are ISO-8601-formatted.

Clone this wiki locally