HTTP API

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.

Warning

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

Related pages

Fields

Content API