Provider Documentation

• 1: Overview
• 2: Concepts
• 3: Getting Started
• 4: Core Tasks
• 4.1: Tooling
• 4.2: Paging
• 4.3: Rate Limiting
• 4.4: Error handling
• 4.5: Retrieving Jobs
• 5: Job Workflow
• 6: Listeners (Preview)
• 7: Testing

1 - Overview

With the Lionbridge Content API a content system connector can:

1. Send content out for translation.
2. Check the status of translation requests
3. Retrieve translated content.

The Provider API translation provider connector can:

1. Retrieve source content sent by content systems
2. Update translation request statuses as they progress within the TMS
3. Send translated content back to content system

Target Audience

This guide is intended for provider connector developers implementing the integration between a translation provider or translation management system (TMS), and the Provider API. The connector will be used to provide translation or language services. This guide assumes the reader is familiar with REST API programming concepts.

For developers looking to implement the integration between a content system and the Content API, please refer to the ContentAPIv2 developer site at the ContentAPIv2 developer site.

Support

For support, please contact connectors@lionbridge.com.

• Getting Started: Get started with the API
• Examples: Check out some example code!

2 - Concepts

Key Concepts

Terms

Provider

A translation provider provides translation services. It is an entity that Provider API users can create, as a target for Content API users to submit jobs for translation or processing.

Job

A job is a container of translation asset tasks that is sent as a single unit to the provider.

AssetTask

Asset tasks are translation tasks for source files. An asset task specifies the necessary information for file transfer, as well as the source language it is in and the target language it needs to be translated into.

SupportAsset

Supporting documents and their metadata. Support assets are not translated by the translation provider, but they provide helpful context for the translator

FileTransfer

An object containing information for transferring source or translated (target) files between the Connector and the translation provider, using the Lionbridge File Management Service (FMS). For more information, please visit the ContentAPI v2 developer page on file transfer.

Listener

Webhook for notifying provider about jobs and asset tasks changes.

TranslationMemory

Updates for previously translated material stored on the provider or TMS.

Status

Jobs

Translation jobs can have the following statuses:

Note that the statuses listed are for ProviderAPI. ContentAPI has a its own list of Job statuses.

AssetTasks

Asset tasks can have the following statuses:

Note that the statuses listed are for ProviderAPI. ContentAPI has a its own list of Request statuses.

3 - Getting Started

Setup

Swagger Documentation

The API swagger documentation can be found here.

Authentication

The Lionbridge connectors team should have provided you with the client id and secret pair to access the Lionbridge Provider API staging environment. You may also be provided with an additional pair to access the Content API for generating test jobs for development and testing purposes. In order to authorize REST API calls, a token must be generated using the id and secret credential.

Use the Lionbridge’s identity endpoint and client credential workflow to obtain access token. Please note that the client id and secret that grant you access to the staging environment do not give you access to the production environment. Lionbridge will provide you with new client id and secret to work in production environment.

To obtain access token, send the following POST request to endpoint https://login.lionbridge.com/connect/token

curl --location --request POST 'https://login.lionbridge.com/connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode 'client_id=xxx' --data-urlencode 'client_secret=XXXXXXXX'

This returns an access token with expiry:

{"access_token":"<encoded token>","expires_in":3600,"token_type":"Bearer","scope":"contentapi.providerv2.staging.default "}

This token has an expiry, typically set to 1 hour (3600s). Once expired, the token is invalid and the user would be required to obtain a new token using the client id and secret. The recommendation for users is to obtain the token, and reuse it during future calls until it expires. This avoids unnecessary exposure of the client secret.

See the Auth0 page on client credential flow for more information about client credential flow.

Disclaimer: Staging environment is NOT meant for production. Data submitted to staging environment may be wiped out without notice.

Create a provider

Use the obtained token to access the API by including it in the header. For example, below is a sample call to create a provider, using cURL:

curl -X 'POST' "https://<api-address>/v2/providers" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <encoded token>"  -d '{
  "name": "MyFirstProvider",
  "siteId": "ACMECorp"
}'

Here, we are creating a provider with a name and siteId. The name can be set as you see fit. The siteId controls which ContentAPI user(s) can access this provider. In this case, the users belonging to ACMECorp are the ones who can submit jobs to this provider. When your provider connector is ready for integration, Lionbridge connectors team will provide you the siteId’s to establish the required routing between you and ContentAPI users.

The response shows the created provider,

{
  "name": "MyFirstProvider",
  "siteId": "ACMECorp",
  "id": "SmKgdqRCRwGHsMHuiyTzGA",
  "creatorId": "<uuid>"
}

4 - Core Tasks

OpenAPI Specification

The API is written in OpenAPI 3.0 format. The specification is published here. The page can also be used for invoking methods using an access token, described earlier under Authentication.

4.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

4.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

4.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.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.

4.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

5 - Job Workflow

Job workflow

Start processing a job

Method: PATCH /providers/{providerId}/jobs/{jobId}

To indicate your connector has started processing this job, use the PATCH job method with the “statusCode” set to “IN_TRANSLATION”.

{
  "statusCode": "IN_TRANSLATION"
}

This lets the submitter know the job has been received by the provider, and prevents the job from appearing when querying for new jobs on the next invocation. Depending on TMS, this may be the point where a job or project will be set up on the TMS side.

Get asset tasks

Method: GET /providers/{providerId}/jobs/{jobId}/assetTasks

Next, use this method to query for a list of Asset Tasks under this job. Each asset task includes the following information:

• source and target languages
• file name
• file transfer information

These allow the source content to be retrieved.

Get support assets (Optional)

Method: GET ​/providers​/{providerId}​/jobs​/{jobId}​/supportAssets

The job may include support assets, which are reference material that aids translation work but are not meant to be translated. Like asset tasks, they can be retrieved as files to be included when submitting the source content to TMS.

Start processing each asset task

Method: PATCH ​/providers​/{providerId}​/jobs​/{jobId}​/assetTasks​/{assetTaskId}

Indicate your connector has started processing asset tasks. For each asset task, use the PATCH method with “statusCode” set to “IN_TRANSLATION”.

{
  "statusCode": "IN_TRANSLATION"
}

Retrieve source file

Method: GET ​/providers​/{providerId}​/jobs​/{jobId}​/assetTasks​/{assetTaskId}​/sourceFile

This method is used to download the source file of an asset task. Note that the method uses HTTP redirect, by returning a 307 response code. Clients are expected to follow the url in the Location header. Most HTTP client libraries do this automatically or can be enabled by a configuration setting. For example, cURL has a -L option.

Note that it is not uncommon for multiple asset tasks to share the same source fileId, when the same file is used for multiple target languages. Efficient handling of this scenario can reduce the ‘chattiness’ of the integration and improve turnaround time.

Perform translation

Now that the source file and all metadata related to the asset task have been retrieved, the connector can submit the asset task into TMS.

Initiate upload of translated file

Method: POST ​/providers​/{providerId}​/jobs​/{jobId}​/assetTasks​/{assetTaskId}​/translatedFile

When the source file has been translated, the connector should upload the translated file. This is a 2-step process. The POST method listed is the first step. It returns a FileTransfer object which contains the necessary information for uploading the file to Lionbridge FMS. For more information, please visit the ContentAPI v2 developer page on file transfer.

Set asset task state

Method: PATCH ​/providers​/{providerId}​/jobs​/{jobId}​/assetTasks​/{assetTaskId}​

Once the translated file has been uploaded, use the PATCH method with:

{
  "statusCode": "TRANSLATION_SUBMITTED",
  "translatedFileId": "<fmsFileId of the translated file>",
}

This signals the asset task has been translated, and is ready for review by the job submitter.

6 - Listeners (Preview)

Usage

Assuming your connector can listen to webhooks at URL: https://provider-connector/callback. Create a listener on the API:

Method: POST ​/listeners​

With the following request body:

{
  "jobUri": "https://provider-connector/callback",
  "jobStatusCodes": [
    "SENDING_READY_FOR_RETRIEVE"
  ]
}

This creates a global listener that generates events on jobs that are submitted by ContentAPI users, for all providers created by the provider connector. Here is a sample callback:

{
  "providerId": "u6QpOENThlh26P",
  "jobId": "SBXT8hZS",
  "eventType": "JOB_UPDATE",
  "updateTime": "2021-09-20T14:40:26.178Z",
  "statusCode": "SENDING_READY_FOR_RETRIEVE"
}

For more information on the different types of listeners that can be created, as well as details on various fields on the callback object, please refer to the API specification.

Optional: Signature Validation

When a listener is created with the LB_PROVIDERAPI_SIGNATURE auth type, which is the default, a signature will be included in the callback request header x-lionbridge-providerapi-signature. This can be used to validate the payload sender is Lionbridge.

To validate a request:

1. Create a hash with the auth secret when creating the listener, along with the payload
2. Compare created hash with the signature header value.

The hash is generated using a hash-based message authentication code (HMAC) with SHA-256. For sample code, please visit this page.

Here is an example with Java, where secret is the auth secret, and Message is the payload JSON message body.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public class ApiSecurityExample {
  public static void main(String[] args) {
    try {
     String secret = "secret";
     String message = "Message";

     Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
     SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
     sha256_HMAC.init(secret_key);

     String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
     System.out.println(hash);
    }
    catch (Exception e){
     System.out.println("Error");
    }
   }
}

Events

Below are some events that may be relevant. Refer to the API specification for up-to-date information on available events and callback payload format.

New job submission

Create a listener, specifying the jobUri and include SENDING_READY_FOR_RETRIEVE in the jobStatusCodes field:

{
  "jobUri": "https://provider-connector/callback",
  "jobStatusCodes": [
    "SENDING_READY_FOR_RETRIEVE"
  ]
}

Here is a sample callback:

{
  "providerId": "u6QpOENThlh26P",
  "jobId": "SBXT8hZS",
  "eventType": "JOB_UPDATE",
  "updateTime": "2021-09-20T14:40:26.178Z",
  "statusCode": "SENDING_READY_FOR_RETRIEVE"
}

Job archival and deletion

Job deletion and archival events are implicitly included when jobUri is defined on a listener. They are always triggered regardless of the jobStatusCodes values of a listener. Here is a sample callback:

{
  "providerId": "u6QpOENThlh26P",
  "jobId": "SBXT8hZS",
  "eventType": "JOB_UPDATE",
  "updateTime": "2021-09-20T14:49:03.284Z",
  "statusCode": "COMPLETED",
  "archived": true,
  "deleted": false
}

Asset task Rejection

TODO

Asset task Approval

TODO

Best Practice

Return 200 quickly

The recommended approach for integration is to always accept the callback upon receipt. A typical approach would be to:

1. Accept the payload and immediately return HTTP 200 OK.
2. Perform business logic as necessary,
3. Or discard the event.

The endpoint may receive many requests depending on activities on the API. Consider separating the event ingestion in Step 1 and asynchronosly perform business logic in Step 2.

Error handling and Retries

The user-specified endpoint is expected to return 200 on success. If the callback delivery fails, the API retries for up to 24 hours with an exponential backoff.

Ordering

Due to the nature of webhook delivery, events are not guaranteed to be in order. For example, a job was first set to COMPLETE status and subsequently archived. Suppose the endpoint was not available when the COMPLETE webhook was sent, but recovered when the job was archived. The archived webhook would arrived first, then later the COMPLETE webhook on the next retry. Ensure the integration can handle out-of-order events gracefully.

Tools

The same approach outlined on Testing can be used to generate test events for listeners. In addition, here are some tools that can help during the development phase:

1. webhook.site This site can be used as a test endpoint for inspecting the webhook payload.

2. ngrok This tool can be used to expose an endpoint on a development environment for the API to reach.

7 - Testing

To validate the connector, you can use the sample scripts for ContentAPIv2 to create test jobs. The sample code repository is located at https://bitbucket.org/liox-ondemand/liox-content-api-client/src/master/

To get started,

1. obtain ContentAPIv2 credentials
2. clone the repo
3. cd curl/File%20Workflow/
4. run each step in sequence to submit a job with a sample source file, using the providerId created by your ProviderAPI connector

For more information on the sequence of actions, visit the ContentAPIv2 workflow page, under heading When the content to translate is a file.