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 data

  • POST: To create new data

  • PUT: To modify existing data

  • DELETE: 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
Response Headers
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

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
Response Headers
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

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
Response Headers
Response JSON Object

  • name (string) – object full name (author/dataformat/version)

  • url (string) – URL where to retrieve the object directly

Status Codes

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
Response Headers
Status Codes

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
Status Codes

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
Status Codes

Sharing an existing data format

POST /api/v1/dataformats/(author)/(dataformat)/(int: version)/share/

Shares an existing data format with a set of users and/or teams. Returns the current sharing status.

Example request:

POST /api/v1/dataformats/johndoe/dataformatA/1/share/
Host: www.beat-eu.org/platform
Authorization: Token 12345
Content-Type: application/json
Content-Length: 50

{
  "users": ["jake", "anna"],
  "teams": ["rookies"]
}

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "status": "shared",
}
Request Headers
Response Headers
Response JSON Object

  • status (string) – how the data format is shared

Status Codes

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
Response Headers
Response JSON Object

  • diff (string) – a string containing all the differences between the various fields of the data format

Status Codes

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
Response Headers
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

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
Response Headers
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

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
Response Headers
Response JSON Object

  • name (string) – the full name (author/algorithm/version)

  • url (string) – URL where to retrieve the object directly

Status Codes

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
Response Headers
Response JSON Object

  • used (boolean) – true if the algorithm name is already used

  • name (string) – the full name (author/algorithm/version)

Status Codes

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
Status Codes

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
Status Codes

Sharing an existing algorithm

POST /api/v1/algorithms/(author)/(algorithm)/(int: version)/share/

Shares an existing algorithm with a set of users and/or teams. Returns the current sharing status.

Example request:

POST /api/v1/algorithms/johndoe/algorithmA/1/share/
Host: www.beat-eu.org/platform
Authorization: Token 12345
Content-Type: application/json
Content-Length: 50

{
  "users": ["jake", "anna"],
  "teams": ["rookies"]
}

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "status": "shared",
}
Request Headers
Response Headers
Response JSON Object

  • status (string) – how the algorithm is shared

Status Codes

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
Response Headers
Response JSON Object

  • diff (string) – a string containing all the differences between the various fields of the algorithm

Status Codes

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
Response Headers
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

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
Response Headers
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

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
Response Headers
Status Codes

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
Response Headers
Response JSON Object

  • used (boolean) – true if the library name is already used

  • name (string) – sanitized library name

Status Codes

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
Status Codes

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
Status Codes

Sharing an existing library

POST /api/v1/libraries/(author)/(library)/(int: version)/share/

Shares an existing library with a set of users and/or teams. Returns the current sharing status.

Example request:

POST /api/v1/libraries/johndoe/libraryA/1/share/
Host: www.beat-eu.org/platform
Authorization: Token 12345

{
  "users": ["jake", "anna"],
  "teams": ["rookies"]
}

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "status": "shared",
}
Request Headers
Response Headers
Response JSON Object

  • status (string) – how the library is shared

Status Codes

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
Response Headers
Response JSON Object

  • diff (string) – a string containing all the differences between the various fields of the library

Status Codes

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
Response Headers
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

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
Response Headers
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

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
Response Headers
Status Codes

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
Response Headers
Status Codes

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
Status Codes

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
Status Codes

Sharing an existing toolchain

POST /api/v1/toolchains/(author)/(toolchain)/(int: version)/share/

Shares an existing toolchain with a set of users and/or teams. Returns the current sharing status.

Example request:

POST /api/v1/toolchains/johndoe/toolchainA/1/share/
Host: www.beat-eu.org/platform
Authorization: Token 12345
Content-Type: application/json
Content-Length: 50

{
  "users": ["jake", "anna"],
  "teams": ["rookies"]
}

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "status": "shared",
}
Request Headers
Response Headers
Response JSON Object

  • status (string) – how the toolchain is shared

Status Codes

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
Response Headers
Response JSON Object

  • diff (string) – a string containing all the differences between the various fields of the toolchains.

Status Codes

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
Response Headers
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

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
Response Headers
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

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

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

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
Status Codes

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
Request JSON Object

  • configuration (json) – the JSON configuration of the experiment

  • label (string) – an experiment label

  • toolchain (string) – the toolchain used

Response Headers
Status Codes

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
Status Codes

Sharing an existing experiment

POST /api/v1/experiments/(author)/(toolchain_fullname)/(experiment)/

Shares an existing experiment with a set of users and/or teams. Returns the current sharing status.

Example request:

POST /api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/share/
Host: www.beat-eu.org/platform
Authorization: Token 12345
Content-Type: application/json

{
  "users": ["jake", "anna"],
  "teams": ["rookies"]
}

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
  "algorithms":
    {
    },
  "status": "public"
}

Example response:

HTTP/1.1 200 OK
Request Headers
Request JSON Object

  • status (string) – how the experiment is shared

  • status – how the experiment is shared

Status Codes

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
Response Headers
Response JSON Object

  • results (json) – the results of the experiment in a JSON object

Status Codes

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
Response Headers
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

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
Response Headers
Status Codes

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
Response Headers
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

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
Response Headers
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

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
Status Codes

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
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 a Bad Request (400) reply. The web server should avoid displaying the reason for failure in case of Internal Server Error(s) (500). It is implemented this way to cope with external test/debugging.

Status Codes

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 of Internal Server Error(s) (500). It is implemented this way to cope for external test/debugging.

Request Headers
Status Codes

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

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

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
Response Headers
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

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
Response Headers
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

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
Response Headers
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

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

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
Status Codes

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
Status Codes

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
Response Headers
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

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
Response Headers
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

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
Status Codes

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
Status Codes