Cyclotis - REST query API

The REST query server is designed to be an interface between any client and the database, with the possibility to read and write inside already created memories. It should not be confused with REST creation API, which is designed to create or delete existing memories.

Both OmegaT and Trados client are already capable of using this interface. The following documentation is only useful if you want to write a new plugin for your favorite CAT tool which is not yet in the list.

Note also that the documentation can be extracted from the source code using the script build-doc.pl, included in the archive. And it is probably more up to date than what you will find here.

HTTP routes

GET /(:db/)?:table/:cmd(.:fmt)?
POST /(:db/)?:table(.fmt)?
DELETE /:table(.fmt)??context=xxx&src=yyy

Exact format of the url is modifiable in the config file (see example in config.yml). Here you can see default format.

GET /(:db/)?:table/:cmd(.:fmt)?

Does a query in the database and shows the results.

In the given URL, replace :xxx by the desired value for the given parameter. Parameters in parenthesis with '?' are optional. Other parameters can be set as usual in a GET query, putting them after '?' in the URL.

Sample 1: GET /myDb/myTable/fuzzy?query=This+is+a+test will call table myTable from database myDb, and do a fuzzy search with the phrase "This is a test".

Sample 2: GET /myDb/myTable/fuzzy.tmx?query=This+is+a+test is identical except that the result will be in tmx format.

Route parameters (given by :xxx in the URL):

db: The database to be connected to; in most servers you should use only one database, that's why this argument is optional; it is not possible to create databases on the fly, so ask server administrator for list of available databases
table: The table (memory, from user point of view) to call
fmt : desired output format. Default is a pipe-separated values, with one line per result. Other possibilities are tmx, perl, json and yaml. Formats may have parameters, read the documentation in the downloaded version for details.
cmd : command, or in other terms, which kind of query you want to do
- fuzzy : searches for phrases which are similar in terms of Levenshtein distance
- exact : searches for exactly this string in the source.
- like : does a LIKE search in SQL
- concSrc, concTra : concordance search - the database contains common words with the searched phrase (grammatical inflexions accepted)
- all : returns all results after a given date (used by project mode in OmegaT)
- glosSrc, glosTra : glossary search - the database contains the given words (grammatical inflexions accepted), nothing more

Extra parameters (given after ? by the user):

query

The text to be searched in the database (except for command "all", where query is a timestamp)

uniq

Filter returned lines using a list of fields: if two lines have the same values for given fields, only the last one (according date) is returned

For the format of this parameter, see Silvestris::Cyclotis::Format::line, parameter cols.

version

Returns only segments valid at the given date. The table must be versionned.

langSrc,langTra

Language for the source and target.

Actually, only used in association with concordance (see next parameters) in order to select the correct analyzer, or for format tmx to set the correct values for xml:lang parameter. In case you want to use a different value for tmx-specific parameters, put tmx.langSrc and tmx.langTra in the URL instead.

POST /(:db/)?:table(.fmt)?

Reads the POST contents and adds an entry to the database. Parameters have same meaning as in previous command.

Data (except database and table name) cannot be put in the URL, they must be in the body of the HTTP request. By default, they must be in application-www-urlencoded format and contain only one entry. You can use input formats by specifying the used format as HTTP 'Content-Type' header (not in the URL: format specified at end of URL is used for the output, not for the input format!), in which case multiple lines are supported.

Note that you cannot specify the date, the system will always make use of the system date (at server side) during insertion.

Extra parameters (given in the contents of POST query):

If content-type = form-urlencoded : All columns, except date and changedate
else: Contents is similar to a result from search. Will use all columns except date and changedate.

DELETE /(:db/)?:table(.fmt)??context=xxx&src=yyy

Delete lines from the table. Either context or src must be provided, not necessairly both.

Note. Forbidden by default, you must declare an URL to activate it.

Format specified at end of URL is used for the output, not for the input format.