This article provides an overview of the public API. This API gives you a full access to all features available in Oddjob.Web - translation management application available at https://oddjob.moravia.com.
The API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The API uses bearer authentication which is 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 a cryptic 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 successfully authenticate against Moravia Azure AD Login, you need to have Client Id, Client Secret and Service Account. Send an email to Moravia Support requesting the client credentials.
Once you have the credentials, make a POST request to Moravia Login in the following format:
POST /oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com/{tenant-id}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id= <client_id>
&client_secret= <client_secret>
&scope=api://59b43490-8253-40a4-8525-db8a005c1c87/.default
You should receive a response in the following format:
{
"access_token": "",
"expires_in": 3600,
"token_type": "Bearer"
}
The access token is valid for 3600 seconds, please do not request a new token with each request, you should renew it shortly before it expires.
Since the authentication uses the client_credentials flow (i.e. you do not need to store the password), we also need the service account username to be sent alongside all your requests. Please include it in the request header in the following format: X-Oddjob-Client:DOMAIN\UserName.
You can download a C# sample code that implements the authentication and token renewal here.
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 an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Oddjob's servers.
| 200 - OK | Everything worked as expected. |
|---|---|
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | No valid API key provided. |
| 402 - Request Failed | The parameters were valid but the request failed. |
| 403 - Forbidden | The API key doesn't have permissions to perform the request. |
| 404 - Not Found | The 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 Errors | Something went wrong on Oddjob's end. |