Getting started

Cleanlist Web Services API (WS-API) is a secure channel, based on web standards, that allows access to various Cleanlist services. This is a technical guide to help you get started.

Endpoints

All requests are made to the server using POST method over HTTPS. Request and response payloads are encoded in JSON.

The format for all WS-API endpoints is:

https://wsapi.staging.cleanlist.ca/api/<service>/

Authentication

When your Cleanlist support contact sets up your account, you will be given an Access Token. This Access Token uniquely identifies you to the the API service, and is used to determine access rights to services.

NOTE: The Access Token is sensitive, as it allows access to the WS-API system on your behalf. Keep it a secret.

Requests to WS-API authenticate themselves via an Authorization HTTP header. The header pattern is:

Authorization: Token {token}

For instance, if your Access Token is "abc123", then this header should be added to your HTTP request:

Authorization: Token abc123

Request Data

WS-API processes a single record, encoded as a JSON object, and returns the same.

For example, to call the pub_echo service, which simply returns the output passed to it as a result payload, one could use curl like this:

curl -X POST 'https://wsapi.staging.cleanlist.ca/api/pub_echo/' \
 -H 'Content-type: application/json' \
 -d '{"greeting": "hello, WS-API world"}'

and the response might be:

{
  "ok": true,
  "req_id": "a656d991-147e-4d55-95e9-f9b50e1aa619",
  "result": {"greeting": "hello, WS-API world"}
}

Response Data

The HTTP response from the server will be of Content-Type: application/json, and will have this general format:

{
  "ok": true or false,
  "req_id": request_id,
  "result": response_payload_object
}

Request IDs

All API service responses, successful or not, will have a unique req_id property, which is a unique request identifier. When contacting Cleanlist tech support regarding WS-API issues, please include this identifier when describing the issue.

Success Responses

In the case of a successful call, the response's HTTP status code is 200 (OK), ok will be true, and result will be an object containing the business payload of the call. The individual keys returned will vary depending on the API service requested; however, they will be consistent for any particular version of an API service.

Error Responses

In the case of an unsuccessful call, ok will be false, and the returned structure will look like this:

{
  "ok": false,
  "req_id": request_id,
  "error": {"error_code": error_code, "error_msg": error_msg}
}

In these cases, error_code will be a short code describing the type of error, and error_msg will be a more specific description of the problem.

Various Common Errors

In the case of an unknown API service name being specified, an HTTP 404 (Not Found) error will be indicated, along with a JSON error result indicating that the service is unknown.

In the case that a request is made to a service to which the client is unauthorized, an HTTP 403 (Forbidden) response code is returned.

Refreshing your token

If you need to obtain a new token – whether periodically or because you believe your current token has been compromised – you can use the Refresh Token API.

curl -X POST 'https://wsapi.staging.cleanlist.ca/api/_refresh/' -H 'Authorization: Token abc123'

Please note that your existing token will be immediately and irrevocably rescinded, and a new one will be issued.

{
  "ok": true,
  "req_id": "f142bfc7-e00b-47bd-93ca-2f24e50e6f72",
  "result": {"new_token": "xyz789"}
}

Be sure to save the new token and use it for future requests.