Public API Overview

This article provides an overview of the public API. The API gives you access to the features available in Oddjob.Web, the translation management application available at https://oddjob.moravia.com.

The API is organized around REST. It has predictable, resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Documentation »

Public and Internal Endpoints

The Oddjob API consists of two groups of endpoints:

  • Public endpoints are intended for RWS partners and vendors. They are described in the Oddjob API Vendor v1 Swagger definition. This is the only definition that third parties may use, and it is kept backward compatible.
  • Internal endpoints are described in the Oddjob API v1, Oddjob API v2 and any other Swagger definitions. They are for RWS internal use only, must not be shared with third parties, and may change or be removed without notice. These definitions are not published on the internet-facing address of the API.

If you are integrating with Oddjob as a partner, build your integration against the Oddjob API Vendor v1 definition only. If you need functionality that it does not provide, contact RWS Support.

Authentication

The API uses bearer authentication, an HTTP authentication scheme that involves security tokens called bearer tokens. The name “bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is an opaque string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources:

Authorization: Bearer <access_token>

To authenticate against Microsoft Entra ID (formerly Azure AD), you need a Client ID and a Client Secret. Send an email to RWS Support to request the client credentials.

Once you have the credentials, make a POST request to the Microsoft login endpoint in the following format:

                        POST /{tenant-id}/oauth2/v2.0/token HTTP/1.1
                        Host: login.microsoftonline.com
                        Content-Type: application/x-www-form-urlencoded

                        grant_type=client_credentials
                         &client_id=<client_id>
                         &client_secret=<client_secret>
                         &scope=api://e6ed52f9-41db-4044-a2d9-c102183f9b78/.default

Tenant ID: ead220ab-1743-4c57-83ae-e055f3401f19

Scope: api://e6ed52f9-41db-4044-a2d9-c102183f9b78/.default

You should receive a response in the following format:

                        {
                            "token_type": "Bearer",
                            "expires_in": 3599,
                            "ext_expires_in": 3599,
                            "access_token": "<access_token>"
                        }

The access token is valid for 3599 seconds. Please do not request a new token for each request; reuse the token and renew it shortly before it expires.

Because authentication uses the client credentials flow, no user password needs to be stored.

Errors

Oddjob uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate that the request failed because of the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error on Oddjob's servers.

200 - OKEverything worked as expected.
400 - Bad Request The request was unacceptable, often due to a missing required parameter.
401 - UnauthorizedNo valid access token was provided.
402 - Request FailedThe parameters were valid but the request failed.
403 - ForbiddenThe access token doesn't have permission to perform the request.
404 - Not FoundThe requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server ErrorsSomething went wrong on Oddjob's end.