RESTful API
The component "DataAccess" allows access to DataSources via command line or a RESTful interface.
Contents
v1
DataAccess provides a command "v1". It allows access to DataSources configured with permissions. In CLI the synopsis is as follows:
v1 [<outputModule>] <dataAccessName> [<elementId>] [apikey=<apiKey>] [<options>]
Piping data into this command will be interpreted like a PUT request to the RESTful API.
Using the RESTful interface the syntax is as follows:
/api/v1/<outputModule>/<dataAccessName>/[<elementId>][?apikey=<apiKey>][<options>]
Arguments
<outputModule>
The name of an output module. Currently known output modules are "json" and "raw". See output modules for more info.
<dataAccessName>
The name of the DataAccess to interact with. The DataSource associated with it is implicitly used.
<elementId>
If this is specified, output is limited to the element with this ID, otherwise all entries are returned. If the ID of a DataSource has multiple fields (combined key), do join them by a slash.
<apiKey>
This allows you to specify the API key if you authenticate by API key.
<options>
Options are key/value pairs. In CLI they are separated by a space, in RESTful interface by ampersand.
The following options are currently known:
| Key | Synopsis | Description | Example |
|---|---|---|---|
order
|
[<field>]=<direction>[&...]
|
Orders the output by <field> in direction <direction> where <direction> can be one of ASC or DESC.
Multiple fields can be specified. Precedence follows occurrence in set option |
order[id]=ASC&order[name]=DESC
|
filter
|
[<field>][<operation>]=<value>
|
Limits output to elements that meet all specified conditions. Expects an array. Default operation is eq. For an exhaustive list of available operations see DataSource.
Note: Currently this is not supported via CLI.
|
filter[name][eq]=bla&filter[done][eq]=1
|
limit
|
<limit>[,<offset>]
|
Limits the output to <limit> elements beginning at <offset>.
If option is not set, then Note: The
meta property of the response of a GET-request does always contain the following data that could be used to implement a paging algorithm on the client side:
|
limit=30,60
|
locale
|
<locale>
|
Sets the locale used to set or get localized fields. | locale=de_CH
|
version
|
<version>
|
Set to next version number on PUT and PATCH requests.
|
version=3
|
Here's an example using all options in CLI and RESTful interface notation:
./cx v1 calendar-event apikey=123 order=id/ASC limit=7 locale=de_CH
/api/v1/json/calendar-event/?apikey=1&order=id/ASC&filter[invitationSent][eq]=1&limit=7&locale=de_CH
Input type
The input is treated according to the content_type header of the request. Currently there's no way to specify the input format for CLI requests. The following content types are currently supported:
| Content type | Treated as | Remarks |
|---|---|---|
| application/x-www-form-urlencoded | URL encoded data | This is the default |
| application/json | JSON encoded data. A single "null" is not allowed | Not yet supported, in development |
| multipart/form-data | Not yet implemented |
Output modules
| Name | Description | Remarks |
|---|---|---|
| json | JSON encoded output containing metadata. See JSON output module. | |
| cli | Produces formatted, human readable output; arrays are converted to tables. | Only available in CLI mode. Do not use this for automated processing! |
| raw | Outputs binary data. | Only available for MediaSource. You must request exactly one file. |
JSON
The JSON output module returns the following JSON structure:
{
"status":<status>,
"meta":<meta_info>,
"messages":<messages>,
"data":<data>
}
- status is "ok" or "error".
- meta contains non further specified data about the result.
- messages contains an array with user messages.
- data contains the requested data as a JSON object.
