Skip to content

RESTful API

Jump to bottom
jakub-krauz edited this page Nov 5, 2014 · 43 revisions

Provided RESTful API

A RESTful web-service endpoint is available for testing and production servers. Web-services are secured using basic authentication. When a user wants to access them he/she has to create an account first:

A framework to generate graphical templates from a database structure is implemented. The idea of implemented framework is described here: http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=6645264

Querying Available Templates

Several URLs access templates available on the server. They support only the GET method. Both XML and JSON responses are supported, XML being the default one. JSON can be requested using the Accept header in the HTTP request:

Accept: application/json

Provided URLs:

/rest/form-layouts/count[?type=<templateType>&form=<formName>]

It returns two values (1) number of templates owned by the current user and (2) number of all templates. There are two optional parameters:

  • type - Restricts results to a given template type. Currently supported values are ODML-GUI and ODML-EEGBASE.
  • form - Restricts results to a given form (there can be more templates for one form).

If none of them is provided all currently available templates are used.

/rest/form-layouts/available[?type=<type>&form=<name>&mineOnly=true]

It returns a list of available templates. Every entry of the list contains the name of the form, the name of the layout and the type of the template. There are three optional parameters:

  • type - Restricts results to a given template type. Currently supported values are ODML-GUI and ODML-EEGBASE.
  • form - Restricts results to a given form (there can be more templates for one form).
  • mineOnly - If set to true, only templates owned by the current user are returned.

If none of them is provided all currently available templates are listed.

/rest/form-layouts/form/count

Functionality of this URL is similar to the first one, but this one returns number of distinct forms for which at least one template is available.

/rest/form-layouts/form/available[?mineOnly=true]

This URL is similar to the second one, except this one returns list of names of distinct forms for which at least one template is available. The mineOnly parameter can be used again.

Transferring Templates

Only the XML format is supported. The URL is following:

/rest/form-layouts?form=<formName>&layout=<layoutName>

A client can use all CRUD operations:

  • GET downloads a template from the server.
  • POST uploads a new template to the server.
  • PUT updates a template owned by the current user.
  • DELETE deletes a template owned by the current user. For POST and PUT requests the content-type must be application/xml.

Transferring Data

The URL is following:

/rest/form-layouts/data?entity=<entityName>&type=<type>[&id=<recordId>]

It supports only the XML format again. The entity parameter denotes the required data entity. Its name can be found in an odML template as the type attribute of a section. For example, if the odML template contains section of type "Person" then the entity name is "Person". The type parameter determines the type of odML document, supported values are ODML-GUI and ODML-EEGBASE. Unlike with templates, only two operations are supported for this URL:

  • GET downloads an odML document with all records of the given entity, or with just one record specified by the optional id parameter.
  • POST uploads an odML document with a new record to the server. It returns ID of the created record.

In addition the service provides two more URLs so as a client can query for existing data records similarly to querying for available templates. They support both the XML and JSON responses.

  • /rest/form-layouts/data/count?entity=<entityName> This URL returns the number of records for the given entity.
  • /rest/form-layouts/data/ids?entity=<entityName> Returns a list of all records' IDs (for the given entity).

Data References

A data object can reference other data objects stored in EEGBase's database. In order to achieve this in odML documents we have introduced a special property named "id". The odML document can either specify all required properties of a given data entity, or use just the id property which means the object is already stored in database. In the latter case the referenced data can be obtained using the URL for data transfer (see above) with the id attribute set. If a client application wants to reference existing records in uploaded data it MUST use this approach, i.e. reference existing data records with the property named "id". Otherwise the data record is considered new and will be created in the database.

Clone this wiki locally