Web API¶
Introduction¶
External clients can access the platform via a REST API that allows them (among other things) to:
Create, retrieve, modify and delete a data format
Create, retrieve, modify and delete an algorithm
Create, retrieve, modify and delete a library
Create, retrieve, modify and delete a toolchain
Configure, retrieve, modify, run, cancel, delete and attest an experiment
Retrieve the results of a particular experiment
Retrieve the list of available databases
Create, retrieve, modify and delete a team
Create, retrieve, modify and delete a search
Retrieve back-end information
The website itself acts as a client of the Web API: when an user action on the website requires that the platform performs some job (like for example save the source code of an algorithm), the corresponding request to the Web API is sent by the browser of the user.
Privacy¶
The current implementation ensures that it is possible for a user to access both own data, as well as data that was shared with him by other users or made public.
User authentication¶
Parts of the API are accessible to all including unauthenticated users (e.g. lists of public algorithms, experiments etc.). However, several operations such as running an experiment requires the user to be authenticated with its existing account on the platform. Some privileged operations also requires the user to be the author of the object on which the action should be performed.
Note
The Web API is only accessible via HTTPS!
To authenticate itself to use the Web API, a client can use the following methods:
Token Authentication
Basic Authentication
The token can be retrieved on the settings page of the user. Basic authentication is done using the user’s username and password.
For the rest of the documentation, the token authentication method will be used in all examples.
Usage of the API¶
Clients can use the platform by sending HTTP requests to it. The response will contain either the result or an error code. In some cases additional information might also be part of the answer (e.g. field error)
The input content type must be understandable by a JSON parser. The API will reject calls using anything else.
The following HTTP methods are used by the API
GET
: To retrieve existing dataPOST
: To create new dataPUT
: To modify existing dataDELETE
: To delete existing data
The data returned by most of the responses are in JSON format.
A GET
request usually takes the following form:
GET <url> HTTP/1.1
Host: <servername>:<port>
Authorization: Token <user-secret-token>
A POST
request usually takes the following form:
POST <url> HTTP/1.1
Host: <servername>:<port>
Authorization: Token <user-secret-key>
Content-Type: <mime-type>
Content-Length: <size>
<content>
In the remainder of this section, we describe in details the REST API.
The following examples assumes that:
the username is
johndoe
the token is
12345
the server is located at
www.beat-eu.org/platform
Data Format API¶
Retrieving a list of all the data formats accessible by the user¶
- GET /api/v1/dataformats/¶
Returns a list of data formats accessible by the current user. The return value is a JSON array containing one description object for each data format.
Example request:
GET /api/v1/dataformats/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "public", "creation_date" "2015-05-27T13:20:20.370760" "declaration": { "#description": "A simple example data format", "json_of_my_dataformat": [ 0, { "label": "string", "x": [ 0, "float64" ] "y": [ 0, "float64" ] } ] } "description": "", "extend": null, "fork_of": null, "hash": "f28c2fd3d5863d7d3f0a421ee6dd56b36b13326bd6f40f50ec350fdb4478c8dd", "is_owner": true, "last_version": true, "modifiable": false, "name": "johndoe/dataformatA/1", "previous_version": null, "sharing": { "status": "public" }, "short_description": "A simple example data format", "version": 1 }, ... ]
- Query Parameters
latest_versions – if true, return only the latest version of each data format
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
creation_date (string) – date of creation of this data format version
declaration (json) – the declaration, which includes a (short) description as well as the JSON declaration of the data format.
description (string) – a description.
extend (string) – a data format, which is extended by this data format (if any), null otherwise
fork_of (string) – parent data format name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/dataformat/version)
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this data format is shared
short_description (string) – a short description
version (integer) – object version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific data format¶
- GET /api/v1/dataformats/(author)/(dataformat)/¶
- GET /api/v1/dataformats/(author)/(dataformat)/(int: version)/¶
Returns a specific data format. If the version is not specified, returns the latest version available to the user. The return value is a JSON array containing a description object for the data format.
Example request:
GET /api/v1/dataformats/johndoe/dataformatA/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "declaration": "{\n"#description": "An example data format", "my_own_dataformat": ...}", "deletable": false, "description": "", "fork_of": null, "modifiable": false, "name": "johndoe/dataformatA/1", "short_description": "An example data format", "version": 1 }
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
declaration (json) – the declaration, which includes a (short) description as well as the JSON declaration of the data format.
deletable (boolean) – is this object still deletable (i.e. not used by anything else)
description (string) – a description.
fork_of (string) – its parent data format name if it is a fork, null otherwise.
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/dataformat/version)
short_description (string) – a short description
version (integer) – its version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No data format with this name/version found
Note
If the version number isn’t specified, the latest accessible version of the data format is returned.
Creating a new data format¶
- POST /api/v1/dataformats/¶
Creates an empty data format. This will return a JSON object containing the sanitized version of the data format (in case the one provided in the request contained invalid characters) and the URL at which the newly-created data format is accessible.
Example request:
POST /api/v1/dataformats/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 48 name=dataformatC&description=example+data+format
Example response:
HTTP/1.0 201 CREATED Content-Type: application/json Location: https://www.beat-eu.org/platform/api/v1/dataformats/johndoe/dataformatC/ { "name": "dataformatC", "url": https://www.beat-eu.org/platform/api/v1/dataformats/johndoe/dataformatC/ }
- Query Parameters
name – the name of the data format
description – (optional) a description of the data format
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
name (string) – object full name (author/dataformat/version)
url (string) – URL where to retrieve the object directly
- Status Codes
200 OK – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the name is already used)
403 Forbidden – Invalid credentials
Note
It is also possible to provides the name, the description as well as the data format declaration in a JSON-like structure, instead of the URL encoded structure.
Checking the validity of a data format name¶
- POST /api/v1/dataformats/check_name/¶
Checks the validity of a data format name. This will return a JSON object containing the sanitized version of the name of the data format (in case the one provided in the request contained invalid characters) and a flag indicating if it is already used.
Example request:
POST /api/v1/dataformats/check_name/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 17 name=dataformat+C
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "dataformat-C" }
- Query Parameters
name – the name to validate
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Updating an existing data format¶
- PUT /api/v1/dataformats/(author)/(dataformat)/¶
Updates an existing data format. This does not return any object.
Example request:
PUT /api/v1/dataformats/johndoe/dataformatA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 407 { "declaration": { ... } }
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
400 Bad Request – Either parameters are missing or wrong (e.g. the short description is too long)
403 Forbidden – Invalid credentials
404 Not Found – Request update to non-existing data format
Deleting an existing data format¶
- DELETE /api/v1/dataformats/(author)/(dataformat)/¶
Deletes an existing data format. This does not return any object.
Example request:
DELETE /api/v1/algorithms/johndoe/dataformatA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing data format
Comparing two data formats¶
- GET /api/v1/dataformats/diff/(author1)/(dataformat1)/(int: version1)/(author2)/(dataformat2)/(int: version2)/¶
Compares two data formats (or two versions of the same data format). The return value is a JSON array containing field named diff the associated value being a (potentially long) string listing all the differences, similar to the output of the diff command line utility.
Example request:
GET /api/v1/dataformats/diff/johndoe/dataformatA/1/johndoe/dataformatA/2/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ "x": "uint32"" }
- Query Parameters
fields – the name of the JSON fields to return. The declaration and the code are always returned by default.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
diff (string) – a string containing all the differences between the various fields of the data format
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No data format with this name/version found
Algorithm API¶
Retrieving a list of all the algorithms accessible by the user¶
- GET /api/v1/algorithms/¶
Returns a list of algorithms accessible by the current user. The return value is a JSON array containing one description object for each algorithm.
Example request:
GET /api/v1/algorithms/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "accessibility": "public", "creation_date" "2015-05-27T13:20:20.370760" "declaration": { "description": "A simple example algorithm", "groups": [ { inputs: { "input_frames": { "type": "system/array_3d_uint8/1" }, "id": { "type": "uint64" } } outputs: { "output": { "type": "system/array_1d_float64/1" } } }, ], "language": "python", "parameters": { "nb_components": { "type": "uint32", "default": 8, "description": "the number of components" } }, "splittable": true } "description": "", "fork_of": null, "hash": "7187849831f7371c2a5bba8363b5e5573fa37a076f73301c5e2b5f592e1288ed", "is_owner": true, "last_version": true, "modifiable": false, "name": "johndoe/algorithmA/1", "opensource": true, "previous_version": null, "sharing": { "status": "public" }, "short_description": "A simple example algorithm", "version": 1 }, ... ]
- Query Parameters
latest_versions – if true, return only the latest version of each data format
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
creation_date (string) – date of creation of this algorithm version
declaration (json) – the declaration, which includes a (short) description, the groups (inputs/outputs), the programming language, the parameters of the algorithm and whether it can be automatically parallelized (splittable) or not.
description (string) – a description
fork_of (string) – parent algorithm name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/algorithm/version)
opensource (boolean) – true if this object is open source
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this algorithm is shared
short_description (string) – a short description
version (integer) – object version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific algorithm¶
- GET /api/v1/algorithms/(author)/(algorithm)/¶
- GET /api/v1/algorithms/(author)/(algorithm)/(int: version)/¶
Returns a specific algorithm. If the version is not specified, this returns the latest version available to the user. The return value is a JSON array containing a description object for the algorithm.
Example request:
GET /api/v1/algorithms/johndoe/algorithmA/1/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "johndoe/algorithmA/1", "declaration": { "description": "A simple example algorithm", "groups": [ { inputs: { "input_frames": { "type": "system/array_3d_uint8/1" }, "id": { "type": "uint64" } } outputs: { "output": { "type": "system/array_1d_float64/1" } } }, ], "language": "python", "parameters": { "nb_components": { "type": "uint32", "default": 8, "description": "the number of components" } }, "splittable": true }, "code": "import bob\n\nclass Algorithm..." }
- Query Parameters
fields – the name of the JSON fields to return. The declaration and the code are always returned by default.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
accessibility (string) – accessibility level (e.g. public, private etc.)
code (string) – the source code
creation_date (string) – date of creation of this algorithm version
declaration (json) – the declaration, which includes a (short) description, the groups (inputs/outputs), the programming language, the parameters of the algorithm and whether it can be automatically parallelized (splittable) or not.
description (string) – a description
fork_of (string) – parent algorithm name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/algorithm/version)
opensource (boolean) – true if this object is open source
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this algorithm is shared
short_description (string) – a short description
version (integer) – its version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No algorithm with this name/version found
Creating a new algorithm¶
- POST /api/v1/algorithms/¶
Creates an empty algorithm. This will return a JSON object containing the sanitized version of the algorithm (in case the one provided in the request contained invalid characters) and the URL at which the newly-created algorithm is accessible.
Example request:
POST /api/v1/algorithms/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 45 name=algorithmC&description=example+algorithm
Example response:
HTTP/1.0 201 CREATED Content-Type: application/json Location: https://beat-eu.org/platform/api/v1/algorithms/johndoe/algorithmC/1/ { "name": "algorithmC", "url": "https://www.beat-eu.org/platform/api/v1/algorithms/johndoe/algorithmC/1/" }
- Query Parameters
name – the name of the algorithm
description – (optional) a description of the algorithm
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
name (string) – the full name (author/algorithm/version)
url (string) – URL where to retrieve the object directly
- Status Codes
201 Created – No error
400 Bad Request – either parameters are missing or wrong (e.g. the short description is too long)
403 Forbidden – Invalid credentials
Note
It is also possible to provides the name, the description as well as the algorithm declaration and code in a JSON-like structure, instead of the URL encoded structure.
Checking the validity of an algorithm name¶
- POST /api/v1/algorithms/check_name/¶
Checks the validity of an algorithm name. This will return a JSON object containing the sanitized version of the name of the algorithm (in case the one provided in the request contained invalid characters) and a flag indicating whether the name is already used.
Example request:
POST /api/v1/algorithms/check_name/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 16 name=algorithm+C
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "algorithm-C" }
- Query Parameters
name – the name to validate
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
used (boolean) – true if the algorithm name is already used
name (string) – the full name (author/algorithm/version)
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Updating an existing algorithm¶
- PUT /api/v1/algorithms/(author)/(algorithm)/¶
Updates an existing algorithm. This does not return any object.
Example request:
PUT /api/v1/algorithms/johndoe/algorithmA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 407 { "declaration": { ... }, "code": "import bob\n\nclass Algorithm..." }
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
400 Bad Request – Either parameters are missing or wrong (e.g. the short description is too long)
403 Forbidden – Invalid credentials
404 Not Found – Request update to non-existing algorithm
Deleting an existing algorithm¶
- DELETE /api/v1/algorithms/(author)/(algorithm)/¶
Deletes an existing algorithm. This does not return any object.
Example request:
DELETE /api/v1/algorithms/johndoe/algorithmA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing algorithm
Comparing two algorithms¶
- GET /api/v1/algorithms/diff/(author1)/(algorithm1)/(int: version1)/(author2)/(algorithm2)/(int: version2)/¶
Compares two algorithms (or two versions of the same algorithm). The return value is a JSON array containing field named diff the associated value being a (potentially long) string listing all the differences, similar to the output of the diff command line utility.
Example request:
GET /api/v1/algorithms/diff/johndoe/algorithmA/1/johndoe/algorithmA/2/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ import numpy\n..." }
- Query Parameters
fields – the name of the JSON fields to return. The declaration and the code are always returned by default.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
diff (string) – a string containing all the differences between the various fields of the algorithm
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No algorithm with this name/version found
Library API¶
Retrieving a list of all the libraries accessible by the user¶
- GET /api/v1/libraries/¶
Returns a list of libraries accessible by the current user. The return value is a JSON array containing one description object for each library.
Example request:
GET /api/v1/libraries/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "public", "creation_date" "2015-05-27T13:20:20.370760" "declaration": { "description": "A simple example algorithm", "language": "python", "uses": { } } "description": "", "fork_of": null, "hash": "89c35c8e9f0030e317ef4689332a80baa0677063dbfbc1f1cfa04c5eae596e07", "is_owner": true, "last_version": true, "modifiable": false, "name": "johndoe/libraryA/1", "opensource": true, "previous_version": null, "sharing": { "status": "public" }, "short_description": "A simple example library", "version": 1 }, ... ]
- Query Parameters
latest_versions – if true return only the latest version of each library
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
creation_date (string) – date of creation of this library version
declaration (json) – the declaration, which includes a (short) description, the programming language, and the libraries that are used by this library.
description (string) – a description
fork_of (string) – parent library name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/library/version)
opensource (boolean) – true if this object is open source
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this library is shared
short_description (string) – a short description
version (integer) – object version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific library¶
- GET /api/v1/libraries/(author)/(library)/¶
- GET /api/v1/libraries/(author)/(library)/(int: version)/¶
Returns a specific library. If the version is not specified, this returns the latest version available to the user. The return value is a JSON array containing a description object for the algorithm.
Example request:
GET /api/v1/library/johndoe/libraryA/1/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "johndoe/libraryA/1", "declaration": { "description": "A simple example algorithm", "language": "python", "uses": { } }, "code": "import bob\n\ndef myfunction(x, y)..." }
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
accessibility (string) – accessibility level (e.g. public, private etc.)
code (string) – the source code
creation_date (string) – date of creation of this library version
declaration (json) – the declaration, which includes a (short) description, the programming language, and the libraries that are used by this library.
description (string) – a description
fork_of (string) – parent library name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/library/version)
opensource (boolean) – true if this object is open source
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this library is shared
short_description (string) – a short description
version (integer) – its version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No algorithm with this name/version found
Creating a new library¶
- POST /api/v1/libraries/¶
Creates an empty library. This will return a JSON object containing the sanitized version of the name of the library (in case the one provided in the request contained invalid characters) and the URL at which the newly-created library is accessible.
Example request:
POST /api/v1/libraries/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 43 name=libraryC&description=example+library
Example response:
HTTP/1.0 201 CREATED Content-Type: application/json Location: https://beat-eu.org/platform/api/v1/libraries/johndoe/libraryC/1/ { "name": "libraryC", "url": "https://www.beat-eu.org/platform/api/v1/libraries/johndoe/libraryC/1/" }
- Query Parameters
name – the name of the library
description – (optional) a description of the library
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Status Codes
201 Created – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the name is already used)
403 Forbidden – Invalid credentials
Note
It is also possible to provides the name, the description as well as the library declaration and code in a JSON-like structure, instead of the URL encoded structure.
Checking the validity of a library name¶
- POST /api/v1/libraries/check_name/¶
Checks the validity of an library name. This will return a JSON object containing the sanitized version of the name of the library (in case the one provided in the request contained invalid characters) and a flag indicating whether the name is already used.
Example request:
POST /api/v1/libraries/check_name/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 14 name=library+C
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "library-C" }
- Query Parameters
name – the name to validate
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
used (boolean) – true if the library name is already used
name (string) – sanitized library name
- Status Codes
200 OK – No error
400 Bad Request – either parameters are missing or wrong (e.g. the name is already used)
403 Forbidden – invalid credentials
Updating an existing library¶
- PUT /api/v1/libraries/(author)/(library)/¶
Updates an existing library. This does not return any object.
Example request:
PUT /api/v1/libraries/johndoe/libraryA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 407 { "declaration": { ... }, "code": "import bob\n\ndef myfunction(x, y):..." }
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
400 Bad Request – Either parameters are missing or wrong (e.g. the name is already used)
403 Forbidden – Invalid credentials
404 Not Found – Request update to non-existing library
Deleting an existing library¶
- DELETE /api/v1/libraries/(author)/(library)/¶
Deletes an existing library. This does not return any object.
Example request:
DELETE /api/v1/libraries/johndoe/libraryA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing library
Comparing two libraries¶
- GET /api/v1/libraries/diff/(author1)/(library1)/(int: version1)/(author2)/(library2)/(int: version2)/¶
Compares two libraries (or two versions of the same library). The return value is a JSON array containing field named diff the associated value being a (potentially long) string listing all the differences, similar to the output of the diff command line utility.
Example request:
GET /api/v1/libraries/diff/johndoe/libraryA/1/johndoe/libraryB/1/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ import numpy\n..." }
- Query Parameters
fields – the name of the JSON fields to return. The declaration and the code are always returned by default.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
diff (string) – a string containing all the differences between the various fields of the library
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No library with this name/version found
Toolchain API¶
Retrieving a list of all the toolchains accessible by the user¶
- GET /api/v1/toolchains/¶
Returns a list of toolchains accessible by the current user. The return value is a JSON array containing one description object for each toolchain.
Example request:
GET /api/v1/toolchains/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "public", "creation_date": "2015-05-27T13:20:18.899512", "declaration": { "description": "Simple example toolchain", "blocks": [ ... ], "databases": [ ... ], "connections": [ ... ], "results": [ ... ] }, "description": "This toolchain implements ...", "fork_of: null, "hash: "65fef19d55738019ec5fdb4050ecdd3e26a710bf5793faf5519924087b1f0c23", "is_owner: true, "last_version: true, "modifiable: false, "name: "johndoe/toolchainA/1", "previous_version: null, "sharing: { "status": "public" }, "short_description": "Simple example toolchain", "version": 1 }, ... ]
- Query Parameters
latest_versions – if true return only the latest version of each toolchain
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
creation_date (string) – date of creation of this toolchain version
declaration (json) – the declaration, which includes a (short) description as well as the JSON declaration of the toolchain.
description (string) – a description.
fork_of (string) – parent toolchain name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/toolchain/version)
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this toolchain is shared
short_description (string) – a short description
version (integer) – object version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific toolchain¶
- GET /api/v1/toolchains/(author)/(toolchain)/¶
- GET /api/v1/toolchains/(author)/(toolchain)/(version)/¶
Returns a specific toolchain. If the version is not specified, this returns the latest version available to the user. The return value is a JSON array containing a description object for the toolchain.
Example request:
GET /api/v1/toolchains/johndoe/toolchainA/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "accessibility": "public", "attestation": null, "creation_date": "2015-05-27T13:20:18.899512", "declaration": { "description": "Simple example toolchain", "blocks": [ ... ], "databases": [ ... ], "connections": [ ... ], "results": [ ... ] }, "description": "This toolchain implements ...", "fork_of: null, "hash: "65fef19d55738019ec5fdb4050ecdd3e26a710bf5793faf5519924087b1f0c23", "is_owner: true, "last_version: true, "modifiable: false, "name: "johndoe/toolchainA/1", "previous_version: null, "sharing: { "status": "public" }, "short_description": "Simple example toolchain", "version": 1 }
- Query Parameters
fields – the name of the JSON fields to return. The declaration is always returned by default.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
accessibility (string) – accessibility level (e.g. public, private etc.)
attestation (json) – information about the attestation
creation_date (string) – date of creation of this toolchain version
declaration (json) – the declaration, which includes a (short) description as well as the JSON declaration of the toolchain.
deletable (boolean) – true if this object can be deleted
description (string) – a description.
fork_of (string) – parent toolchain name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
is_owner (boolean) – true if the caller owns the object
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/toolchain/version)
previous_version (integer) – previous version, null otherwise
sharing (json) – information about how this toolchain is shared
short_description (string) – a short description
version (integer) – its version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No toolchain with this name/version found
Creating a new toolchain¶
- POST /api/v1/toolchains/¶
Creates an empty toolchain. This will return a JSON object containing the sanitized version of the name of the toolchain (in case the one provided in the request contained invalid characters) and the URL at which the newly-created toolchain is accessible.
Example request:
POST /api/v1/toolchains/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 45 name=toolchainC&description=example+toolchain
Example response:
HTTP/1.0 201 CREATED Content-Type: application/json Location: https://www.beat-eu.org/platform/api/v1/toolchains/johndoe/toolchainC/1/ { "name": "toolchainC", "url": "https://www.beat-eu.org/platform/api/v1/toolchains/johndoe/toolchainC/1/" }
- Query Parameters
name – the name of the toolchain
description – (optional) a description of the toolchain
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Status Codes
201 Created – No error
400 Bad Request – some required parameters are missing in the request
403 Forbidden – Invalid credentials
Note
It is also possible to provides the name, the description as well as the toolchain declaration in a JSON-like structure, instead of the URL encoded structure.
Checking the validity of a toolchain name¶
- POST /api/v1/toolchains/check_name/¶
Checks the validity of a toolchain name. This will return a JSON object containing the sanitized version of the name of the toolchain (in case the one provided in the request contained invalid characters) and a flag indicating whether the name is already used.
Example request:
POST /api/v1/toolchains/check_name/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 16 name=toolchain+C
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "toolchain-C" }
- Query Parameters
name – the name to validate
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Status Codes
200 OK – No error
400 Bad Request – Either parameters are missing or wrong
403 Forbidden – Invalid credentials
Updating an existing toolchain¶
- PUT /api/v1/toolchains/(author)/(toolchain)/¶
Updates an existing toolchain. This does not return any object.
Example request:
PUT /api/v1/toolchains/johndoe/toolchainA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 407 { "declaration": { ... } }
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
200 OK – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the short description is too long)
403 Forbidden – Invalid credentials
404 Not Found – Request update to non-existing toolchain
Deleting an existing toolchain¶
- DELETE /api/v1/toolchains/(author)/(toolchain)/¶
Deletes an existing toolchain. This does not return any object.
Example request:
DELETE /api/v1/algorithms/johndoe/toolchainA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing toolchain
Comparing two toolchains¶
- GET /api/v1/toolchains/diff/(author1)/(toolchain1)/(int: version1)/(author2)/(toolchain2)/(int: version2)/¶
Compares two toolchains (or two versions of the same toolchain). The return value is a JSON array containing field named diff the associated value being a (potentially long) string listing all the differences, similar to the output of the diff command line utility.
Example request:
GET /api/v1/toolchains/diff/johndoe/toolchainA/1/johndoe/toolchainA/2/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ "inputA": ..." }
- Query Parameters
fields – the name of the JSON fields to return. The declaration is always returned by default.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
diff (string) – a string containing all the differences between the various fields of the toolchains.
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No toolchain with this name/version found
Experiment API¶
Retrieving a list of all the experiments accessible by the user¶
- GET /api/v1/experiments/¶
- GET /api/v1/experiments/(author)/¶
Returns a list of experiments accessible by the current user. The return value is a JSON array containing one description object for each experiment..
Example request:
GET /api/v1/experiments/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "public", "attestation_locked": null, "attestation_number": null, "cpu_time": 0, "creation_date": "2015-05-27T13:22:31.544454", "data_read": 0, "data_written": 0, "datasets": [ "atnt.idiap_test_eyepos.train", "atnt.idiap_test_eyepos.dev_templates", "atnt.idiap_test_eyepos.dev_probes", "atnt.idiap_test_eyepos.test_templates", "atnt.idiap_test_eyepos.test_probes" ] "duration": "-", "end_date": null, "fullname": "johndoe/johndoe/eigenface/1/myexp", "is_owner": true, "label": "myexp", "modifiable": false, "short_description": "", "start_date": null, "status": "Pending", "toolchain": "johndoe/eigenface/1" }, ... ]
- Query Parameters
include_fields – the optional fields to include in the answer
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
attestation_locked (boolean) – tristate: if an attestation is associated, contains the lock state else null
attestation_number (string) – an attestation number if an attestation is associated, null otherwise
cputime (integer) – the cputime required to run this experiment
creation_date (string) – date of creation of this experiment
data_read (string) – amount of data read
data_written (string) – amount of data written
datasets (json) – the database datasets attached
duration (string) – the duration
end_date (string) – the end date
fullname (string) – object full name (author/toolchain_fullname/experiment_label)
is_owner (boolean) – true if the caller owns the object
label (string) – object label
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
short_description (string) – a short description
start_date (string) – the start date
status (string) – the experiment status such as Pending, Done, etc.
toolchain (string) – the attached toolchain
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific experiment¶
- GET /api/v1/experiments/(author)/(toolchain_fullname)/(experiment)/¶
Returns a specific experiment. The return value is a JSON array containing a description object for the experiment.
Example request:
GET /api/v1/experiment/johndoe/johndoe/toolchainA/1/myexp/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "configuration": { "analyzers": { ... }, "blocks": { ... }, "datasets": { ... }, "globals": { ... }, }, "description": "", "done": true, "failed": false, "sharing": { status: "public" }, "status": "public", "short_description": "" }
- Query Parameters
fields – the name of the JSON fields to return.
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
configuration (json) – the JSON configuration of the experiment
description (string) – a description
done (boolean) – true if the experiment has completed
failed (boolean) – true if the experiment has failed
sharing (json) – information about how this experiment is shared
status (string) – the status of the experiment
short_description (string) – a short description
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No experiment with this name/version found
Creating a new experiment¶
- POST /api/v1/experiments/(author)/¶
Creates a new experiment. This does not return any object.
Example request:
POST /api/v1/experiments/johndoe/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 787 { "configuration": { "analyzers": { ... }, "blocks": { ... }, "datasets": { ... }, "globals": { ... }, }, "label": "myexp2", "toolchain": "johndoe/toolchainA/1" }
Example response:
HTTP/1.0 201 CREATED Content-Type: application/json Location: http://www.beat-eu.org/api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/
- Request Headers
Authorization – optional credentials for authentication
Content-Type – This should return
application/json
- Request JSON Object
configuration (json) – the JSON configuration of the experiment
label (string) – an experiment label
toolchain (string) – the toolchain used
- Response Headers
Location – The location of the newly created experiment
Content-Type – This should return
application/json
- Status Codes
201 Created – no error
400 Bad Request – Either parameters are missing or wrong (e.g. the short description is too long)
403 Forbidden – Invalid credentials
Updating an existing experiment¶
- PUT /api/v1/experiments/(author)/(toolchain_fullname)/(experiment)/¶
Updates an existing experiment. This does not return any object.
Example request:
PUT /api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 812 { "configuration": { "analyzers": { ... }, "blocks": { ... }, "datasets": { ... }, "globals": { ... }, }, "label": "myexp2" }
Example response:
HTTP/1.1 200 OK
- Request Headers
Authorization – optional credentials for authentication
Content-Type – This can be
application/json
- Request JSON Object
configuration (json) – the JSON configuration of the experiment
label (string) – an experiment label
toolchain (string) – the toolchain used
- Response Headers
Location – The location of the newly created experiment
Content-Type – This should return
application/json
- Status Codes
200 OK – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the short description is too long)
403 Forbidden – Invalid credentials
404 Not Found – Request update to non-existing experiment
Deleting an existing experiment¶
- DELETE /api/v1/experiments/(author)/(toolchain_fullname)/(experiment)/¶
Deletes an existing experiment. This does not return any object.
Example request:
DELETE /api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing experiment
Starting an existing experiment¶
- POST /api/v1/experiments/(author)/(toolchain_fullname)/(experiment)/start/¶
Starts an existing experiment. This does not return any object.
Example request:
DELETE /api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/start/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length:99 { "name": "johndoe/johndoe/toolchainA/1/myexp2", "url": "/api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/" }
Example response:
HTTP/1.1 200 OK
- Request Headers
Authorization – optional credentials for authentication
Content-Type – This can be
application/json
- Request JSON Object
configuration (json) – the JSON configuration of the experiment
label (string) – an experiment label
toolchain (string) – the toolchain used
- Response Headers
Location – The location of the started experiment
Content-Type – This can be
application/json
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – Request to start a non-existing experiment
Canceling a running experiment¶
- POST /api/v1/experiments/(author)/(toolchain_fullname)/(experiment)/cancel/¶
Cancels a running experiment. This does not return any object.
Example request:
POST /api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/cancel/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 200 OK
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – Request to cancel an experiment, which is not running
Retrieving experiment results from an attestation number¶
- GET /api/v1/experiments/(attestation_number)/¶
Returns the experiment results from an attestation number The return value is a JSON structure containing the experiment results.
Example request:
GET /api/v1/experiments/1595181064/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "results": { "analysis": { "out_data": { "type": "int32", "primary": false, "value": 44 }, ... } } }
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
results (json) – the results of the experiment in a JSON object
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
404 Not Found – No attestation with this number found
Database API¶
Retrieving a list of all the databases accessible by the user¶
- GET /api/v1/databases/¶
Returns a list of databases accessible by the current user. The return value is a JSON array containing one description object for each database.
Example request:
GET /api/v1/databases/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "public", "creation_date": "2015-05-27T13:18:54.853905", "declaration": { "description": "An example database", "protocols": [ { "name": "protocolA", "template": "simple_face_recognition", "sets": [ { "name": "train", "outputs": { "client_id": "system/uint64/1", "file_id": "system/uint64/1", "image": "system/array_2d_uint8/1" } "template": "train", "view": "Train", }, ... ] }, ... ] "root_folder": "/remote/databases/databasA", } "description": "This example database is for...", "fork_of": null, "hash": "", "last_version": true, "modifiable": false, "name": "databaseA/1", "nb_experiments": 7, "nb_experiments_done": 0, "previous_version": null, "short_description": "An example database" "version": 1 }, ... ]
- Query Parameters
latest_versions – if true return only the latest versions of the database
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
creation_date (string) – date of creation of this database version
declaration (json) – the declaration, which includes a (short) description, the root directory where raw data are stored, as well as the JSON declaration of the protocols of the database.
description (string) – a description.
fork_of (string) – parent database name if this object is a fork, null otherwise.
hash (string) – used to determine if two objects have the same content
last_version (boolean) – true if this object is the latest version
modifiable (boolean) – true if this object is still modifiable (i.e. not used by anything else)
name (string) – object full name (author/database/version)
nb_experiments (integer) – the number of experiments that use this database
nb_experiments_done (integer) – the number of completed experiments that use this database
previous_version (integer) – previous version, null otherwise
short_description (string) – a short description
version (integer) – object version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a list of all the database templates accessible by the user¶
- GET /api/v1/databases/templates/¶
Returns a list of database templates accessible by the current user. The return value is a JSON array containing one description object for each database template.
Example request:
GET /api/v1/databases/templates/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "advanced_face_recognition": { "templates": [ "client_id", "eye_centers", "file_id", "image", "template_id" ], "train": [ "client_id", "eye_centers", "file_id", "image" ], "probes": [ "client_id", "eye_centers", "file_id", "image", "probe_id", "template_ids" ] }, ... }
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific database¶
- GET /api/v1/databases/(author)/(database)/¶
- GET /api/v1/databases/(author)/(database)/(int: version)/¶
Returns a specific database. If the version is not specified, this returns the latest version available to the user. The return value is a JSON array containing a description object for the database.
Example request:
GET /api/v1/databases/databaseA/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "accessibility": "public", "code": "import bob\nimport numpy\nimport xbob.db....", "creation_date": "2015-05-27 13:18:54.853905", "declaration": "{\n \"description\": ...}", "description": "This example database is for...", "hash": "", "last_version": true, "name": "atnt/1", "nb_experiments": 7, "nb_experiments_done": 0, "previous_version": null, "short_description": "An example database", "version": 1 }
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
accessibility (string) – accessibility level (e.g. public, private etc.)
code (string) – the code of the corresponding database view
creation_date (string) – date of creation of this database version
declaration (json) – the declaration, which includes a (short) description, the root directory where raw data are stored, as well as the JSON declaration of the protocols of the database.
description (string) – a description.
hash (string) – used to determine if two objects have the same content
last_version (boolean) – true if this object is the latest version
name (string) – object full name (database/version)
nb_experiments (integer) – the number of experiments that use this database
nb_experiments_done (integer) – the number of completed experiments that use this database
previous_version (integer) – previous version, null otherwise
short_description (string) – a short description
version (integer) – its version number
- Status Codes
200 OK – No error
404 Not Found – No database with this name/version found
403 Forbidden – Invalid credentials
Note
If the version number isn’t specified, the latest accessible version of the database is returned.
Backend API¶
Retrieving the scheduler (and workers) state¶
- GET /api/v1/backend/scheduler/¶
Returns the state of the scheduler, the workers and the cache. This command can only be performed by an administrator. The return value is a JSON array containing one description object.
Example request:
GET /api/v1/backend/scheduler/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token <adminkey> Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "cache": { "capacity-in-megabytes": 857172, "free": 302000, "percent-used": 59.7, "size-in-megabytes": 511607, } "scheduler": { "beat_version": "0.3.4", "experiments": { "completed": 0, "list": { }, "running": 0 }, "jobs": { "canceled": 0, "failed": 0, "completed": 0, "running": 0, "queued": 0 }, "queues": { "default": { "status": "Active", "info": "Queue is declared and active", "memory-in-megabytes": 4096, ... }, ... } } "workers": { "node1": { "info": "Worker is declared and active", "memory_in_megabytes": 16026, ... } } }
- Query Parameters
refresh – whether to retrieve information about the workers or to use the previously retrieved data.
- Request Headers
Authorization – administrator credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
cache (json) – information about the cache, such as its capacity in MB, its number of free space.
scheduler (json) – information about the scheduler such as the beat.scheduler version, the number of experiments running and completed, the number of jobs queued, running and completed, as well as queue information
workers (json) – information about the workers such as the amount of memory, the operating system or the environments available.
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
500 Internal Server Error – Could not connect to the scheduler, or the scheduler did not accept the request.
Canceling all the experiments¶
- POST /api/v1/backend/cancel-all-experiments/¶
This will cancel all the scheduled experiments. This does not return any object.
Example request:
POST /api/v1/backend/cancel-all-experiments/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token <adminkey>
Example response:
HTTP/1.0 200 OK
- Request Headers
Authorization – administrator credentials for authentication
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
500 Internal Server Error – Could not connect to the scheduler, or the scheduler did not accept the request.
Updating scheduler configuration¶
- POST /api/v1/backend/queue-configuration/¶
This will update the scheduler configuration. This does not return any object.
Example request:
POST /api/v1/backend/queue-configuration/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token <adminkey> Content-Type: application/json { "1 minute/1G": { "memory-in-megabytes": 1024, "time-limit-in-minutes": 1, "environments": [ { "name": "System Python", "version": "0.1.0" } ], "slots": { "node1": 2, "node2": 2, "node3": 1 } }, ... }
Example response:
HTTP/1.0 200 OK
- Request Headers
Content-Type – This is
application/json
Authorization – administrator credentials for authentication
- Request JSON Object
queue-slot-configuration (json) –
a JSON dictionary, indicating, in details, what is the configuration of each queue on the system and their relationship with each available working node. For the format description, see the example above.
This information is crossed with what is reported by individual workers to the scheduler in order to confirm environment availability. The actual number of computing slots available on every node is irrelevant to this configuration, it only defines the maximum occupancy for a given queue on a given worker. The scheduler is responsible for making sure workers are optimally used given queue and computing power constraints.
While re-configuring, the currently queued jobs are momentarily put on hold. Jobs which are scheduled on queues that don’t exist anymore are automatically canceled.
- Response Headers
Content-Type – This may return
application/text
. In this case, a (multi-line) string that can be used by the server for displaying a reason for the failure back to the user. This string should be displayed to the user in case of aBad Request
(400) reply. The web server should avoid displaying the reason for failure in case ofInternal Server Error(s)
(500). It is implemented this way to cope with external test/debugging.
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
500 Internal Server Error – Could not connect to the scheduler, or the scheduler did not accept the request.
Cleaning-up the cache¶
- POST /api/v1/backend/cache-cleanup/¶
This will clean-up the cache. This may (optionally) return the hashes of the deleted files.
Example request:
POST /api/v1/backend/cache-cleanup/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token <adminkey> nolist=0
Example response:
HTTP/1.0 200 OK [ "ABCewQEQ", "ZRDFQQWD", ... ]
- Query Parameters
olderthan – Cached files with an access-time which is older than current time minus
olderthan
(minutes) will be erased. If this parameter is set to 0, then all files, but those related to the running experiments, will be erased.nolist – (Optional, default: 1) When 0, the Scheduler will return a list of the hashes of the removed files.
- Response Headers
Content-Type – This will return application/json in case of success. The JSON will then contain the list of hashes of the deleted cache file. In case of error, this will return
application/text
. In this case, a (multi-line) string that can be used by the server for displaying a reason for the failure back to the user. The web server should avoid displaying the reason for failure in case ofInternal Server Error(s)
(500). It is implemented this way to cope for external test/debugging.
- Request Headers
Authorization – administrator credentials for authentication
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
500 Internal Server Error – Could not connect to the scheduler, or the scheduler did not accept the request.
Telling a web server that the execution of a block has started¶
- POST /api/v1/backend/block-started/¶
This request is sent once the job is successfully submitted to run on a remote node. It keeps the web server informed so that it can display the state and progress of the currently running experiment. This request does not return any object in case of success.
Example request:
POST /api/v1/backend/block-started/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token <schedulerkey> Content-Type: application/json { 'experiment-name': 'johndoe/toolchain/1/configuration', 'block-name': 'do_this', 'queue-name': 'System Python 8G/3d', 'number-of-slots': 1, 'inputs': [ '91d7e3ba6dfeeb78fa08ed4516389dac6628f0e13e5face8397a17520224e767', 'd2227b04a36cf5362fc4c209d0e666038e6db65a7dd9253fe445c18bcac24f24' ], 'outputs': [ '81d7e3ba6dfeeb78fa08ed4516389dac6628f0e13e5face8397a17520224e767', 'c2227b04a36cf5362fc4c209d0e666038e6db65a7dd9253fe445c18bcac24f24' ] }
Example response:
HTTP/1.0 204 NO CONTENT
- Request Headers
Content-Type – This is application/json.
Authorization – credentials of the scheduler user for authentication
- Request JSON Object
block-info (json) – a JSON dictionary, providing information about the block started, such as its corresponding experiment, and the block name in this experiment (see the example above).
- Response Headers
Content-Type – This will not return in case of success. In case of error 400, this will return
application/text
. In this case, a (multi-line) string that can be used by the server for displaying a reason for the failure back to the user
- Status Codes
200 OK – No error
400 Bad Request – If the web server cannot process the request
403 Forbidden – Invalid credentials
404 Not Found – If the experiment or the block isn’t found
Note
This is a message that is sent to the web server when a given block is allocated
for processing. This allows the web server to know that a given experiment is
being treated. Because of the platform design, it is possible that blocks are not
scheduled for processing because results are already available on the cache. In
these cases, a block-started
message is never issued.
Telling a web server that the execution of a block has finished¶
- POST /api/v1/backend/block-finished/¶
This request is sent once the processing of a block finishes or a cache is found. It keeps the web server informed so that it can display the state and progress of the currently running experiment. This request does not return any object in case of success.
Example request:
POST /api/v1/backend/block-finished/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token <schedulerkey> Content-Type: application/json { 'state': 'processed', 'experiment-name': 'user/toolchain/1/configuration', 'block-name': 'do_this', 'queue-name': 'System Python 8G/3d', 'number-of-slots': 1, 'inputs': [ '91d7e3ba6dfeeb78fa08ed4516389dac6628f0e13e5face8397a17520224e767', 'd2227b04a36cf5362fc4c209d0e666038e6db65a7dd9253fe445c18bcac24f24' ], 'outputs': [ '81d7e3ba6dfeeb78fa08ed4516389dac6628f0e13e5face8397a17520224e767', 'c2227b04a36cf5362fc4c209d0e666038e6db65a7dd9253fe445c18bcac24f24' ], 'worker': 'node01.localhost', 'exit-code': 0, 'stdout': '...', 'stderr': '...', 'error-message': '...', 'statistics': ..., 'timed-out': 0, 'stop-forced': 0 }
Example response:
HTTP/1.0 204 NO CONTENT
- Request Headers
Content-Type – This is application/json.
Authorization – credentials of the scheduler user for authentication
- Request JSON Object
block-info (json) –
a JSON dictionary, providing information about the block started, such as its corresponding experiment, and the block name in this experiment (see the example above).
Note
The variable named
'state'
can also be set to'failed'
, in case the block has failed processing or'canceled'
in case it was directly (by the user) or indirectly canceled (because of a failing block).Note
The
'error-message'
bit is optional and may be omitted if no error occurred.Note
The
'statistics'
bit is optional and may be omitted in case the block is not run (because it is cached).
- Response Headers
Content-Type – This will not return in case of success. In case of error 400, this will return
application/text
. In this case, a (multi-line) string that can be used by the server for displaying a reason for the failure back to the user
- Status Codes
200 OK – No error
400 Bad Request – If the web server cannot process the request
403 Forbidden – Invalid credentials
404 Not Found – If the experiment or the block isn’t found
Retrieving a list of all the environments accessible by the user¶
- GET /api/v1/backend/environments/¶
Returns a list of environments accessible by the current user. The return value is a JSON array containing one description object for each environment.
Example request:
GET /api/v1/backend/environments/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "public", "name": "Scientific Python 2.7", "queues": { "Default": { "max_slots_per_user": 4, "memory_limit": 12288, "nb_cores_per_slot": 1, "nb_slots": 76, "time_limit": 180 }, ... } "short_description": "Scientific Python 2.7", "version": "0.0.3" }, ... ]
- Query Parameters
latest_versions – if true, return only the latest version of each environment
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
name (string) – object name
queues (json) – the processing queues attached to this environment, including the max_slots_per_user, memory_limit, nb_slots, nb_cores_per_slot and the time_limit (in minutes).
short_description (string) – a short description
version (integer) – object version number
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Team API¶
Retrieving a list of all the teams accessible by a user¶
- GET /api/v1/teams/¶
- GET /api/v1/teams/(author)/¶
Returns a list of teams accessible by a user. If the user (author) is not specified, it returns the team of the current user; otherwise it returns the team of the specified user. The return value is a JSON array containing one description object for each team.
Example request:
GET /api/v1/teams/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility":"private", "is_owner": false, "name": "johndoe/does_team", "short_description": "John's example team" }, ... ]
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
is_owner (boolean) – true if the caller owns the object
name (string) – object name
short_description (string) – a short description
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Retrieving a specific team¶
- GET /api/v1/teams/(author)/(team)/¶
Returns a specific team. The return value is a JSON array containing a description object for the database.
Example request:
GET /api/v1/teams/johndoe/does_team/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "accessibility": "private", "is_owner": true, "members": [ "user" ], "name": "johndoe/does_team", "short_description": "John's example team" }
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Object
accessibility (string) – accessibility level (e.g. public, private etc.)
is_owner (boolean) – true if the caller owns the object
members (json) – the list of users belonging to this team
name (string) – object name
short_description (string) – a short description
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Creating a new team¶
- POST /api/v1/teams/(author)/(team)/¶
Creates a new team. This does not return any object.
Example request:
POST /api/v1/teams/johndoe/johns_team/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 129 { accessibility: "private", members: [ "user" ], name: "johns_team", short_description: "Another team example", }
Example response:
HTTP/1.0 201 CREATED
- Request Headers
Authorization – optional credentials for authentication
- JSON Parameters
accessibility (string) – accessibility level (e.g. public, private etc.)
members (json) – the list of users belonging to this team
name (string) – object name
short_description (string) – a short description
- Status Codes
201 Created – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the name is already used)
403 Forbidden – Invalid credentials
Updating an existing team¶
- PUT /api/v1/teams/(author)/(team)/¶
Updates an existing team. This does not return any object.
Example request:
PUT /api/v1/teams/johndoe/johns_team/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 150 { accessibility: "private", members: [ "user" "another_user" ], name: "johns_team", short_description: "Another team example", }
Example response:
HTTP/1.1 200 OK
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
200 OK – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the name is already used)
403 Forbidden – Invalid credentials
404 Not Found – Request update to non-existing team
Deleting an existing team¶
- DELETE /api/v1/teams/(author)/(team)/¶
Deletes an existing team. This does not return any object.
Example request:
DELETE /api/v1/teams/johndoe/johns_team/1/ Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing team
Search API¶
Retrieving a list of all searches accessible by the user¶
- GET /api/v1/search/list/(author)/¶
Returns a list of searches accessible by the user. The return value is a JSON array containing one description object for each search.
Example request:
GET /api/v1/search/list/johndoe/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility": "private", "author": "johndoe", "is_owner": true, "name": "johndoe/a_sample_search", "short_description": "An example search", "user_name": "johndoe" }, ... ]
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
accessibility (string) – accessibility level (e.g. public, private etc.)
author (string) – the author
is_owner (boolean) – true if the caller owns the object
name (string) – object full name (author/search)
user_name (string) – object owner user name
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Creating a new search¶
- POST /api/v1/search/save/¶
Creates a new search. This does not return any object.
Example request:
POST /api/v1/search/save/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 657 { analyzer: "user/integers_echo_analyzer/1", filters: [ { "context": "any-field", "name": null, "operator": "contains-any-of", "value": [ "single" ] } ], "label": "doessearch", "long_description": "", "options": { "order-by": [ "-experiment-date" ] }, "plot_parameters": { } "plot_templates_relationship": { }, "settings": { }, "short_description": "Doc" }
Example response:
HTTP/1.0 201 CREATED
- Request Headers
Authorization – optional credentials for authentication
Content-Type – This should return
application/json
- Request JSON Object
analyzer (string) – the analyzer algorithm
filter (json) – the filtering criteria to select experiments
label (string) – the label of the search
long_description (string) – a long description
options (json) – options such as sort parameters
plot_parameters (json) – plot parameters
plot_templates_relationship (json) – plot template parameters
settings (json) – settings parameters
short_description (string) – a short description
- Status Codes
201 Created – No error
400 Bad Request – some required parameters are missing in the request
403 Forbidden – Invalid credentials
Updating an existing search¶
- PUT /api/v1/search/save/¶
Updates an existing search. This does not return any object.
Example request:
PUT /api/v1/search/save/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/json Content-Length: 832 { analyzer: "user/integers_echo_analyzer/1", filters: [ { "context": "any-field", "name": null, "operator": "contains-any-of", "value": [ "single" ] }, { "context": "any-field", "name": null, "operator": "contains-not", "value": [ "donotselectthisvalue" ] } ], "label": "doessearch", "long_description": "", "options": { "order-by": [ "-experiment-date" ] }, "plot_parameters": { } "plot_templates_relationship": { }, "settings": { }, "short_description": "Doc" }
Example response:
HTTP/1.1 200 OK
- Request Headers
Authorization – optional credentials for authentication
Content-Type – This should return
application/json
- Request JSON Object
analyzer (string) – the analyzer algorithm
filter (json) – the filtering criteria to select experiments
label (string) – the label of the search
long_description (string) – a long description
options (json) – options such as sort parameters
plot_parameters (json) – plot parameters
plot_templates_relationship (json) – plot template parameters
settings (json) – settings parameters
short_description (string) – a short description
- Status Codes
200 OK – No error
400 Bad Request – Either parameters are missing or wrong (e.g. the label is already used)
403 Forbidden – Invalid credentials
404 Not Found – Request update to a non-existing search
Deleting an existing search¶
- DELETE /api/v1/search/(author)/(search)/¶
Deletes an existing search. This does not return any object.
Example request:
DELETE /api/v1/search/johndoe/doessearch/ Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.1 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – No error
403 Forbidden – Invalid credentials
404 Not Found – Request delete to non-existing search
Attestation API¶
Retrieving a list of all attestations of a given user¶
- GET /api/v1/attestations/(author)/¶
Returns a list of all attestations of a given user. The return value is a JSON array containing one description object for each attestation.
Example request:
GET /api/v1/attestations/johndoe/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */*
Example response:
HTTP/1.0 200 OK Content-Type: application/json [ { "creation_date": "2015-05-08 17:08:54.802515", "experiment": "johndoe/johndoe/toolchainA/1/johns_exp1", "locked": false, "nb_algorithms": 4, "nb_dataformats": 6, "number": 958374770, "publication_date": "2015-05-08 17:10:56.123635", "toolchain": "johndoe/toolchainA/1" }, ... ]
- Request Headers
Authorization – optional credentials for authentication
- Response Headers
Content-Type – This should return
application/json
- Response JSON Array of Objects
creation_date (string) – date of creation of this attestation version
experiment (string) – the label of the attested experiment
locked (boolean) – if true, the attestation is locked
nb_algorithms (integer) – the number of algorithms used by this attested experiment
nb_dataformats (integer) – the number of data formats used by this attested experiment
number (integer) – a number to uniquely identify this attestation
publication_date (string) – date of publication of this data attestation
toolchain (string) – the toolchain full name used by the attested experiment
- Status Codes
200 OK – No error
403 Forbidden – Invalid credentials
Creating a new attestation¶
- POST /api/v1/attestations/¶
Creates a new attestation. This does not return any object.
Example request:
POST /api/v1/attestations/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Content-Type: application/x-www-form-urlencoded Content-Length: 36 experiment=johndoe/toolchainA/1/exp1
Example response:
HTTP/1.0 201 CREATED
- Query Parameters
experiment – the full name of the experiment to attest
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
201 Created – no error
400 Bad Request – some required parameters are missing or wrong in the request OR experiment is already attested
403 Forbidden – Invalid credentials
Note
It is also possible to provide the experiment name in a JSON-like structure, instead of the URL encoded structure.
Unlocking an attestation¶
- POST /api/v1/attestations/unlock/(int: attestation_number)/¶
Unlocks an attestation. This does not return any object.
Example request:
POST /api/v1/attestations/unlock/2004723460/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345
Example response:
HTTP/1.0 204 NO CONTENT
- Request Headers
Authorization – optional credentials for authentication
- Status Codes
204 No Content – no error
400 Bad Request – Either parameters are missing or wrong OR the attestation is already unlocked
403 Forbidden – Invalid credentials