Core Tasks

• 1: Tooling
• 2: Paging
• 3: Rate Limiting
• 4: Error handling
• 5: Retrieving Jobs

1 - Tooling

While it is possible to use the API using standard HTTP clients, there are a variety of tools available online can be used to generate client libraries for many programming languages.

Steps, using C# as an example

1. Download the specification file. It is in OpenAPI 3 format, and can be downloaded here.
2. On a web browser, go to the swagger editor.
3. In the Swagger Editor, go to File->Import File, and select the downloaded json file.
4. Once the json is imported, go to Generate Client, and select “csharp”.
5. Download and extract the client package.

This will produce a client package, containing:

• README.md: outlines build requirements, installation, and sample usage
• src: project of the generated C# classes
• docs: markdown documentation generated from Swagger specification

For more information on Swagger Codegen, including how to obtain and use the command-line version of the tool, visit https://github.com/swagger-api/swagger-codegen

2 - Paging

Some of the API calls return a list of items. By default, a call can return at most 50 items. To navigate to the next page, use the pagination.navNext value of the return value. For example, the GET /providers call may return the following,

{
  "pagination": {
    "navNext": "next_page_token"
  },
  "providers": [

    {
      "name": "Test for User1",
      "siteId": "basicRT_dev",
      "id": "X5zsGWs3RhGCgph_unwl1A",
      "creatorId": "c0ffee"
    },
    {
      "name": "Test for User1",
      "siteId": "basicRT_dev",
      "id": "XMbGKLt-TdCDgQdyfKZaFw",
      "creatorId": "c0ffee"
    }
    <more items, snipped>
  ]
}

To get to the next page, invoke the same method, with the navNext parameter included,

GET /providers?navNext=next_page_token

3 - Rate Limiting

By default, the API throttles all client requests.

• For Prod environment, each IP is throttled to 20 requests per second max
• for Staging environment, each IP is throttled to 10 requests per second max

Please note that the limit is subject to change without notice.

Integrations code should always check for HTTP response code 429 and 503 (retryable errors).

If the response contains a “retry-after” attribute, then retry the request after that time; otherwise the integration should implement exponential backoff retry logic with limited number of retries.

4 - Error handling

Implement a catch-and-retry for 50x or 429 (throttling) errors from the API, with an exponential back-off retry interval.

This increases the reliability of the integration. Occasionally, the API can experience load spikes that require additional system resources.

The back end is designed to scale up when these are detected. However, there may be a delay before these capacities are available.

5 - Retrieving Jobs

When building a provider connector, there are two options for retrieving new jobs for processing:

• Polling
• Listeners - aka webhooks.

Polling is suitable for use cases where the number of providers is low, as it requires polling each provider individually.

Using listeners allows the connector to respond to job and asset task events for one or more providers, but requires a publicly accessible endpoint.

Polling

Method: GET /providers/{providerId}/jobs/findByStatus?status=SENDING_READY_FOR_RETRIEVE

The process begins by polling for new jobs that are ready to be translated, by using the method with the status set to SENDING_READY_FOR_RETRIEVE. For each jobId returned, process the job.

Listeners (Preview)

For more on getting new jobs using listeners, see New job submission section under Events