Main menu

API Reference

Loco REST API documentation

General information about the Loco API is available here and includes some examples.

Resources

Authentication

Working with a Loco project via the API requires just a simple key sent over SSL only (actually TLS). There are two ways you can send your key:

Authorization header

The preferred method of authentication is to send your key in the Authorization request header as shown in the raw HTTP request below:

GET /api/auth/verify HTTP/1.1
Host: localise.biz
Authorization: Loco <my_project_key>

Basic authorization is also supported. This can be useful when testing via command line curl as shown below. Note the trailing colon indicating a blank password - this avoids a password prompt in your scripts.

$ curl -u <my_project_key>: https://localise.biz/api/auth/verify

Query string key parameter

You can also send your key by appending endpoints with the key parameter as shown in the URI below:

https://localise.biz/api/auth/verify?key=<my_project_key>

The query string method is convenient when you're not able to set request headers, such as sending somebody a download link or testing in a browser. Note that this method will show your key in our server logs, so is the least secure method. Headers are never logged.

We recommend you only send export keys in the query string, and always send full access keys in the header.

JSON responses

API output is JSON with the exception of the Export API which produces output according to the given file extension (e.g. .xml).

JSON output is beautified by default, but you can append ?ugly to the query string to produce a single line of output. If your JSON parser expects slashes to be escaped as \/ or requires Unicode escape sequences like \u00a3 then use the ugly option to enable compatibility.

It's not mandatory to append .json to API URIs, but it's good practice to add it because the file extension has meaning in some end points. When path arguments contain dots they can be confused with the required file format if it hasn't been specified.

RESTfulness

CRUD operations are mapped to HTTP methods as follows: POST (Create), GET (Read), PATCH (Update) and DELETE (erm.. Delete).

If your client doesn't support fancy HTTP verbs then you may send the method you want as a POST field: e.g. REQUEST_METHOD=DELETE or REQUEST_METHOD=PATCH

Usage limits

The Loco API is not currently rate limited, but there are measures in place to prevent abuse. In lieu of enforced usage caps, please observe our fair usage policy. Stricter rate limiting is likely to be introduced in future. Any such changes will be communicated to all API users before they are rolled out.

Versioning

The current major version of the API is "1", and has remained largely backward-compatible since it was launched. See the changelog for the latest version number and what has changed in each release.

Breaking changes are rare, but to protect yourself from future changes you can request a specific version by appending the "v" parameter to endpoint URIs. e.g. ?v=1.0. Without this parameter you'll get the bleeding edge version of each endpoint. Alternatively you can send the required version in the X-Api-Version header.

The version number (major.minor.patch) will be incremented from time to time as follows:

  • patch: Discreet improvements including new optional parameters. Fully backward-compatible with existing client code.
  • minor: When parameters are deprecated or removed. Client code that doesn't request a specific version may need updating.
  • major: When a new version of the API is totally incompatible with the previous.

Client libraries

We'll gladly list third party libraries if you tell us about them. So far we know about the following projects:

PHP

JavaScript / Node

Java / Android

CLI

  • marten-cz/loco-cli – (in Python), provides push/pull functionality for syncing translations.
  • robrechtme/loco-cli - (in JavaScript), provides push/pull functionality for syncing translations.

Please note that these are not recommendations. They may be out of date, and we can't provide support for third party products.

See also