Start using the Back-End REST APIs

Before integrating our back-end REST APIs, read through the following information to help you get started:

Authentication

Authentication for all of our back-end REST APIs occurs via HTTP Basic Authentication (Basic Auth). The authentication string should be “username:password”. For example, if your username is “johndoe” and your password is “password1234”, your authentication string would be “johndoe:password1234”. And in this case your base64-encoded credentials will be “am9obmRvZTpwYXNzd29yZDEyMzQ=”, as shown in the following example:

curl --request POST \
  --url 'https://rest.cleverbridge.com/urlgenerator/generateusersessionurl' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic am9obmRvZTpwYXNzd29yZDEyMzQ=' \
  --data '{
    "TargetUrl": "https%3A%2F%2Fwww.cleverbridge.com%2F864%2F%3Fscope%3Dcheckout%26amp%3Bcart%3D97771%26amp%3Blanguage%3Den%26amp%3Bcurrency%3DUSD%26amp%3Bx-source%3Dwebsite-visit-05.2019
  }'

Note

To use your username and password to authenticate, your Cleverbridge user must have the following privilege - API User. For more information about user account privileges, see Users ✱.

Header Values

The most relevant REST request header values for our back-end REST APIs are the following:

Field Name Description Example
Values		 Usage
Comments
Accept Format of the function call response that is desired. application/json or application/xml Setting a value is required.
Content-Type Format of the request content. application/json or application/xml Required for POST but not for GET.

In the following example, the requested resource is a json object:

curl --request POST \
  --url 'https://rest.cleverbridge.com/urlgenerator/generateusersessionurl' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "TargetUrl": "https%3A%2F%2Fwww.cleverbridge.com%2F864%2F%3Fscope%3Dcheckout%26amp%3Bcart%3D97771%26amp%3Blanguage%3Den%26amp%3Bcurrency%3DUSD%26amp%3Bx-source%3Dwebsite-visit-05.2019
  }'

Status Codes

The following describes the status codes that result from successful and unsuccessful calls to our REST APIs.

All Cleverbridge REST-based APIs use conventional HTTP response codes to indicate success or failure of an API call. In general:

  • Codes in the 2xx range indicate that the function call was successful.
  • Codes in the 4xx range indicate an error that resulted from an incorrectly specified request (for example, a required parameter was missing or the data type passed in a parameter was incorrect).
  • Codes in the 5xx range indicate an error on the Cleverbridge side.
Status Code Description
200 Successful completion of the call.
400 Bad Request (incomplete message, required fields missing, incorrectly formatted XML/JSON).
401 Unauthorized Request. Authentication with Cleverbridge failed (ID/password problem). Not applicable to Pricing API.
402 Request failed: Invalid parameters.
404 Not Found: The other unique identifier (for example, the subscription ID) set and passed in the call is invalid or does not exist.
500 Request failed due to server error.

Upon calling an API endpoint, check the HTTP header status code.

  1. If the status code is 200, then the call was successful (and the ResultMessage field in the response is blank).
  2. In case of a non-200 status code, the ResultMessage contains more information to assist in diagnosis and error handling. For example:
    • With a 404 status code, the ResultMessage could contain “Item not found.”
    • With a 400 status code, the ResultMessage could contain “Missing required field.”

Testing Your Connection

To test your connectivity with our back-end REST APIs, use the Test Connection resource:

curl --request GET \
  --url https://rest.cleverbridge.com/connection/test \
  --header 'accept: application/json'

This resource validates that:

  • You can connect with rest.cleverbridge.com.
  • Your API user credentials (authentication) are valid.

Rate Limits

To guarantee a stable and reliable performance of our platform, Cleverbridge places limits on the amount of data that can be consumed. API users are limited to a maximum of 150 requests per second from an IP address or range. All API requests count towards the rate limit.

When an individual IPv4 address or IPv6/64 IP range exceeds the per-second request limit, further requests to our API are blocked with an HTTP 429 status code until the block time has expired. This happens after one minute. The HTTP response contains a Retry-After header to indicate when you can resume sending requests.

HTTP/1.1 429 Too Many Requests
Content-Type: text/html
Retry-After: 60

The most likely cause of an HTTP 429 Too Many Requests error is that you perform a batch operation that sends multiple API requests in parallel. To avoid reaching the rate limit with batch operations, observe the following best practices:

  • Send API requests in serial and not in parallel, that is the next call included in the batch operation cannot be made until the current call is completed.
  • Limit concurrent threads that make requests (across all processes and machines) to a maximum of four.

Developer Guides

In the following guides, you can find additional information about each of the back-end REST APIs, including descriptions of how to implement particular use cases:

Reference Documentation

In the following reference documentation, you can find request and response examples, an API explorer, and parameter definitions for each of the back-end REST APIs: