Basics – Livewords Flow Support

API Location

Livewords has two possible locations to which you can make an API connection:

demo: api.demo.livewordsflow.com

production: api.livewordsflow.com

For example, using curl, requests for this version of the API are of the form

curl –u ... https://api.demo.livewordsflow.com/

Notation

We leave out HTTP version references like "HTTP/1.1" in our example http requests and responses in this document.

Security and Authentication

This API is an SSL-only API. Regardless of how your account is configured you authorise against the API using basic authentication with your account domain and API key in the following format.

{account-domain}:{api-key}

For example:

acme:1c92d208e9f899674788fadc5ab66b8a8e05c05d7417c43d

The API key represents your authorization to use the API. This should be confidential and kept secret. You should replace you API key if you have reasons to believe the key is compromised.

Testing Authentication

Using curl you may test your authentication with a given key by sending a GET request to /. For example

curl https://api.demo.livewordsflow.com/
   -u acme:1c92d208e9f899674788fadc5ab66b8a8e05c05d7417c43d
   -H "Content-Type: text/xml"

Upon success, this will display basic version information like

{
  "startupDate" : "2016-01-25 11:39:18",
  "apiKey" : "acme:1c92d...7c43d"
}

Encoding

All HTTP request entities and XML messages in this documentation are using UTF-8 as their character encoding.

Common Headers

You must supply a content type header on a PUT or POST operations. For example you may get a plain text response in case of errors like a bad request and you should treat this as an error you need to take action on.

POST /widgets/items
Content-Type: text/xml

Rate Limiting

To provide a high quality of service for all clients we pose limits on the number of items per minute you may expect to be handled. Each API consumer identified by a given API key is able to make 100 items in each 10 minute time-slot (600 items per hour). We reserve the right to adjust the rate limit for given endpoints but expect this to occur rarely.

If the rate limit is exceeded, Livewords flow may respond with an HTTP 429 Too Many Requestsresponse code. The response may have a Retry-After header that tells you for how many seconds to sleep before retrying.

429 Too Many Requests
Retry-After: 361

Check xml structure (available only on demo planform)

Item xml structure must match to source settings. You can test this from the interface by clicking button "Send test item to xml":

Screen_Shot_2018-04-30_at_11.55.27.png

Item will be send to all linked target languages. You can see results in To Do. You can translate and publish item. After this it will be send to callback URL.

Curl Example

A convenient way to test calls is to use a curl to send POST requests using the contents of a file as the request body with --data-binary and the @ option.

curl https://api.demo.livewordsflow.com/products/items?target-language=nl,fr-FR,de
  -u acme:1c92d208e9f899674788fadc5ab66b8a8e05c05d7417c43d
  -H "Content-Type: text/xml"
  --data-binary @/~john/item1.xml