RESTful API

From Cloudrexx Development Wiki
Jump to: navigation, search

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:

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>/(ASC|DESC)[;...] Orders the output order=id/ASC;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. 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 with <offset>. limit=30,60
locale <locale> Sets the locale used to set or get localized fields. locale=de_CH

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

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.