Content requests
Requesting a localization or creation of new content is done by sending a content request. Content requests can map to anything, but will usually map against a page or product. A minimal request might look like this:
{
"language": {
"source": "sv",
"target": "no"
},
"fields": [
{
"id": "title",
"type": "localizable",
"data": "string",
"value": "Produkter"
},
{
"id": "body",
"type": "localizable",
"data": "html",
"value": "<p>Denna text kan innehålla <strong>HTML taggar</strong></p>"
}
],
"preferences": [
{
"type": "delivery-speed",
"value": "normal"
}
]
}
A content request can contain the following:
Name | Type | Description |
---|---|---|
id |
string | Unique identifier generated when a content request is received by the API. Only readable |
type |
type (string) | The type of request, will be standard if not specified. |
previous |
id (string) | Only used for update requests. Unique identifier of the last version of the content sent. |
language.source |
Locale | Language that the source text, field names and hints is in. Required |
language.target |
Locale | Language that the content should be written in. Required |
fields |
Array[Field] | One or more fields containing either information or something that should be localized or written. Required |
state |
state (string) | State of the request. See section below for details. Only readable |
created |
Timestamp | When the request was received by the API. Only readable |
completed |
Timestamp | When the request was marked as completed. Only readable |
lastStateChange |
Timestamp | When the state of the request was last updated. Only readable |
preferences |
Array[Preference] | A list of preferences for the request. |
Unknown JSON properties on a content request should be ignored. This is important for future compatibility as the HTTP API may introduce new properties at times. Existing fields will never be deleted.
Types
The API supports different types of content requests, the standard
type
represents a simple request for some content to be localized and or created.
Type | Description |
---|---|
standard |
Standard request for localization or content creation. |
import |
Import some already existing content for use with versioning. |
update |
Update a previous content request with some altered content. |
Standard requests
Standard requests are those that have no type
set or those that have type
set to standard
.
Import requests
To support versioning of already localized content it's possible to import content. A content request that is to be imported is similar to a standard request, but is marked with the type import
. In addition to this every field in the request requires both originalValue
and value
. When an import request is sent it is automatically marked as completed as no work will be done with it, you can then reference the id returned when sending update requests.
Example:
{
"type": "import",
"language": {
"source": "sv",
"target": "en"
},
"fields": [
{
"id": "body",
"type": "localizable",
"data": "html",
"originalValue": "<p>Denna text kan innehålla <strong>HTML taggar</strong></p>",
"value": "<p>This text can contain <strong>HTML tags</strong></p>"
}
]
}
Update requests
When you want to send an update to a content request that has been previously
sent (including imported requests) you can mark the request with the type update
.
All fields that would normally be in a standard request should be included in an update. Figuring out what has changed is done via matching the old field values with the new values, this is done by comparing the via their identifier.
It is possible to add on new fields in an update, in which case they are equivalent to fields in a normal content request. If any field that was previously present is not in the update request it treated as the field should be removed, meaning it will not be present when the request is fulfilled.
{
"type": "update",
"previous": "idOfPreviousVersion",
"language": {
"source": "sv",
"target": "en"
},
"fields": [
{
"id": "body",
"type": "localizable",
"data": "html",
"value": "<p>Denna text kan innehålla <strong>HTML taggar och annat</strong></p>"
}
]
}
States
Every content request has a state and will pass through certain states before it is completed.
State | Description |
---|---|
pending |
The request has been received by the API. |
confirmed |
Request has been processed by Contentor and will be fulfilled soon. |
completed |
The request has been completed and the content is ready for use. |
canceled |
The request has been canceled and will not be worked on. |
failed |
The content request has failed at some part of the process, no work worked on it and it will need to be resent. The is most likely due to faulty html content. |
States can change backwards, such as from completed
to confirmed
such as in
the case where a request is reopened for updates.
Fields
Content request are built up of one or more fields. Fields are used both to request a localization of a text, the creation of a text and to deliver contextual information needed to work with a content request.
See format of fields for details about the format used for fields.
Preferences
Preferences for the content request. Currently the following preferences are supported:
type | Description |
---|---|
delivery-speed |
The preferred delivery speed. Currently supports normal and express . |