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>] <dataSource> [<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>/<dataSource>/[<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.

<dataSource>

The name of the DataSource to interact with.

<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

Here's an example using all options in CLI and RESTful interface notation:

./cx v1 calendar-event apikey=123 order=id/ASC limit=7
/api/v1/json/calendar-event/?apikey=1&order=id/ASC&filter[invitationSent][eq]=1&limit=7

Output modules

Name Description Remarks
json JSON encoded output containing metadata. See JSON output module.
raw Output formatted for human readable CLI output. Do not use this for automated processing!

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.