Key Patterns

Authentication

At present we use two different mechanisms for authentication within the Lingo24 APIs; OAuth2 and User_Key. All authentication is performed at an application level, with the credentials for your registered application(s) managed through the developer portal.

Oauth2

The Business Documents API uses the OAuth Version 2 standards for authentication. For this, all requests to the API, except requests to the authentication and authorization endpoints, must include the Authentication header item (Authorization: Bearer {your_access_token}). Before you can use the Business Documents API it must be authorized to access your Lingo24 client details via our Customer Portal. This is achieved by making a GET request to the /oauth2/authorize resource in our Ease Portal.

To do this, users should be redirected to:

https://ease.lingo24.com/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={callback_url}

  • client_id - the Client ID for your application from the developer portal
  • redirect_uri - the URI you would like the user to be redirected to following the issue of an authorization_code.
The result of this step is the provision of an authorization_code that can be used against the /oauth2/access resource of the API to obtain an access_code for use this further API calls.

The following diagram details the requests required for a successful OAuth2 authorisation.

User Key

The Premium MT API uses User_Key authentication. For this, any authenticated API requests require the passing of a user_key parameter containing your applications user_key.

Callbacks

When creating an API account with Lingo24, you can set an optional default callback URL for any projects or jobs created. If set, Lingo24 will post any updates about the project or job as they happen. Callback notifications are sent when:

  • A job has been priced and has metrics available
  • A job is complete and has target files available for review
  • A project is complete.

We will make up to three attempts to submit data to the callback URL. If the end point is not reachable, we will send an email alert and you will need to make a request directly against our API.

Callbacks are modelled as PUT requests and will contain in the contents the JSON data the payloads associated with that resource.

To receive callbacks you must be able to process these requests:

  • PUT /project/{projectId} HTTP/1.1
  • PUT /job/{jobId} HTTP/1.1

As well as setting a global callback URL for your application, it is also possible to specify a URL per-project using the projectCallbackUrl field.

Pagination

To enable end clients to limit the amount of data returned and support pagination, the Business Documents API supports general parameters on GET requests; size, page and sort.

size

If present as a query parameter while a GET request is being made on a collection resource (e.g. /projects) the number of returned entities is limited to the value of the parameter:

  • the value must be greater or equal to 0,
  • if the value is 0, all the entities are returned,
  • in absence of this parameter, a default value is used.

page

If present as a query parameter while a GET request is being made on a collection resource (/projects etc), the entity list returned is offset by the specified size and page combination:

  • the value must be greater or equal to 0,
  • in absence of this parameter, a default value of 0 is used.

sort

If present as a query parameter while a GET request is being made on a collection resource (e.g. /projects), the entity list returned will be sorted depending on the value of the parameter:

  • the value is expected to be a comma seperated list, alternating by filed and direction,
  • valid direction values are desc and asc.

Results

When making a request ot a collection resource (e.g. /projects) the result object will contain information on the collection returned:

  • page - the current page for the result set,
  • size - the current page size for the result set,
  • totalElements - the total number of elements available in the full result set.

Additionally, the response will also contain hyperlinks related to the result set:

  • prev - the previous page for the result set,
  • next - the next page for the result set.