Skip to content

RESTful API

The component "DataAccess" allows access to DataSources via command line or a RESTful interface.

v1

DataAccess provides a command "v1". It allows access to DataSources configured with permissions. In CLI the synopsis is as follows:

1
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:

1
/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.

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 elements beginning at . If option is not set, then is automatically being set to 10. A value greater than 50 is not supported and will be reset to 50.

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: Applied limit (defaults to 10 if option limit has not been set)
  • offset: Applied offset (defaults to 0 if it has not been set through option limit)
  • matched: Total number of entries found (matching the set filter filter if set)
  • count: Number of entries being returned

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:

1
./cx v1 calendar-event apikey=123 order=id/ASC limit=7 locale=de_CH

1
/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:

1
2
3
4
5
6
{
    "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.