translate5 provides a REST API to create, read and manipulate all stored data. REST is a HTTP based, resource oriented architecture.
For further information see: http://en.wikipedia.org/wiki/Representational_state_transfer
Data Format
The data format is JSON. On PUT requests not all data fields must be given, only the fields with changed data are sufficient.
Therefore the HTTP Header Content-Type must be: "application/x-www-form-urlencoded; charset=UTF-8". The form-data body should look like:
// just upload the JSON as raw body
{HERE-DATA-AS-JSON-URL-ENCODED}
//EXCEPTION FOR FILE UPLOADS:
//The JSON can not be transferred as raw HTTP content, but must be put into a form variable named "data".
data = {HERE-DATA-AS-JSON-URL-ENCODED}
The whole JSON string must be URL-encoded, since the content-type "application/x-www-form-urlencoded" requires that.
To see the use of the REST API in action, a developer may have a look on the way translate5 JS-GUI frontend uses the REST API through tools like Firebug. This way it is easy for a programmer, to understand the way it works and to see, which values are used for which resources in which situations.
API backwards compatibility over different application versions
We try to keep a backwards compatibility of the existing API. If the API changes in an incompatible manner this is listed explicitly in the "important release notes" section of each releases changelog.
Adding new fields to an entity is not considered as incompatible change. But if a field is being removed, renamed or the data format changes, this is considered as incompatible change.
Each answer of the API contains a HTTP header field "X-Translate5-Version" which contains the current version of translate5.
Filtering
All GET calls without an ID provide a list of resources. With the GET Parameter “filter” this list can be filtered. In general all fields are filterable. Exceptions in single cases.
Authentication
For all requests the authenticated user must have the right to access the resource in the requested context.
A dynamic authentication via API is implemented with the "Session"-resource.
Editor only usage
Please note, that via API translate5 can be integrated in "Editor only usage", meaning that you can use only the editing component of translate5 and do the user management and task management elsewhere. Please see here.