.. vim: set fileencoding=utf-8 : .. Copyright (c) 2016 Idiap Research Institute, http://www.idiap.ch/ .. .. Contact: beat.support@idiap.ch .. .. .. .. This file is part of the beat.web module of the BEAT platform. .. .. .. .. Commercial License Usage .. .. Licensees holding valid commercial BEAT licenses may use this file in .. .. accordance with the terms contained in a written agreement between you .. .. and Idiap. For further information contact tto@idiap.ch .. .. .. .. Alternatively, this file may be used under the terms of the GNU Affero .. .. Public License version 3 as published by the Free Software and appearing .. .. in the file LICENSE.AGPL included in the packaging of this file. .. .. The BEAT platform is distributed in the hope that it will be useful, but .. .. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY .. .. or FITNESS FOR A PARTICULAR PURPOSE. .. .. .. .. You should have received a copy of the GNU Affero Public License along .. .. with the BEAT platform. If not, see http://www.gnu.org/licenses/. .. .. _beatweb-webapi: Web API ======= .. _beatweb-webapi-introduction: 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. .. _beatweb-webapi-privacy: 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. .. _beatweb-webapi-authentication: 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. .. _beatweb-webapi-usage: 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: .. code-block:: http GET HTTP/1.1 Host: : Authorization: Token A ``POST`` request usually takes the following form: .. code-block:: http POST HTTP/1.1 Host: : Authorization: Token Content-Type: Content-Length: 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`` .. _beatweb-webapi-dataformatapi: Data Format API --------------- .. (openapi: : specs/swagger.yaml) Retrieving a list of all the data formats accessible by the user ................................................................ .. http: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**: .. sourcecode:: http GET /api/v1/dataformats/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 latest_versions: if true, return only the latest version of each data format :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string creation_date: date of creation of this data format version :>jsonarr json declaration: the declaration, which includes a (short) description as well as the JSON declaration of the data format. :>jsonarr string description: a description. :>jsonarr string extend: a data format, which is extended by this data format (if any), null otherwise :>jsonarr string fork_of: parent data format name if this object is a fork, null otherwise. :>jsonarr string hash: used to determine if two objects have the same content :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr boolean last_version: true if this object is the latest version :>jsonarr boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>jsonarr string name: object full name (author/dataformat/version) :>jsonarr integer previous_version: previous version, null otherwise :>jsonarr json sharing: information about how this data format is shared :>jsonarr string short_description: a short description :>jsonarr integer version: object version number :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific data format ................................. .. http:get:: /api/v1/dataformats/(author)/(dataformat)/ .. http: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**: .. sourcecode:: http GET /api/v1/dataformats/johndoe/dataformatA/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json json declaration: the declaration, which includes a (short) description as well as the JSON declaration of the data format. :>json boolean deletable: is this object still deletable (i.e. not used by anything else) :>json string description: a description. :>json string fork_of: its parent data format name if it is a fork, null otherwise. :>json boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>json string name: object full name (author/dataformat/version) :>json string short_description: a short description :>json integer version: its version number :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: 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 .......................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http 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 name: the name of the data format :query description: (optional) a description of the data format :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string name: object full name (author/dataformat/version) :>json string url: URL where to retrieve the object directly :statuscode 200: No error :statuscode 400: Either parameters are missing or wrong (e.g. the name is already used) :statuscode 403: 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 ........................................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "dataformat-C" } :query name: the name to validate :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :statuscode 200: No error :statuscode 403: Invalid credentials Updating an existing data format ................................ .. http:put:: /api/v1/dataformats/(author)/(dataformat)/ Updates an existing data format. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 400: Either parameters are missing or wrong (e.g. the short description is too long) :statuscode 403: Invalid credentials :statuscode 404: Request update to non-existing data format Deleting an existing data format ................................ .. http:delete:: /api/v1/dataformats/(author)/(dataformat)/ Deletes an existing data format. This does not return any object. **Example request**: .. sourcecode:: http DELETE /api/v1/algorithms/johndoe/dataformatA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 **Example response**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing data format Sharing an existing data format ............................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "status": "shared", } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string status: how the data format is shared :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing data format Comparing two data formats .......................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ "x": "uint32"" } :query fields: the name of the JSON fields to return. The declaration and the code are always returned by default. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string diff: a string containing all the differences between the various fields of the data format :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No data format with this name/version found .. _beatweb-webapi-algorithmapi: Algorithm API ------------- Retrieving a list of all the algorithms accessible by the user .............................................................. .. http: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**: .. sourcecode:: http GET /api/v1/algorithms/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 latest_versions: if true, return only the latest version of each data format :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string creation_date: date of creation of this algorithm version :>jsonarr json declaration: 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. :>jsonarr string description: a description :>jsonarr string fork_of: parent algorithm name if this object is a fork, null otherwise. :>jsonarr string hash: used to determine if two objects have the same content :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr boolean last_version: true if this object is the latest version :>jsonarr boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>jsonarr string name: object full name (author/algorithm/version) :>jsonarr boolean opensource: true if this object is open source :>jsonarr integer previous_version: previous version, null otherwise :>jsonarr json sharing: information about how this algorithm is shared :>jsonarr string short_description: a short description :>jsonarr integer version: object version number :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific algorithm ............................... .. http:get:: /api/v1/algorithms/(author)/(algorithm)/ .. http: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**: .. sourcecode:: http GET /api/v1/algorithms/johndoe/algorithmA/1/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 fields: the name of the JSON fields to return. The declaration and the code are always returned by default. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string accessibility: accessibility level (e.g. public, private etc.) :>json string code: the source code :>json string creation_date: date of creation of this algorithm version :>json json declaration: 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. :>json string description: a description :>json string fork_of: parent algorithm name if this object is a fork, null otherwise. :>json string hash: used to determine if two objects have the same content :>json boolean is_owner: true if the caller owns the object :>json boolean last_version: true if this object is the latest version :>json boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>json string name: object full name (author/algorithm/version) :>json boolean opensource: true if this object is open source :>json integer previous_version: previous version, null otherwise :>json json sharing: information about how this algorithm is shared :>json string short_description: a short description :>json integer version: its version number :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No algorithm with this name/version found Creating a new algorithm ........................ .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http 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 name: the name of the algorithm :query description: (optional) a description of the algorithm :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string name: the full name (author/algorithm/version) :>json string url: URL where to retrieve the object directly :statuscode 201: No error :statuscode 400: either parameters are missing or wrong (e.g. the short description is too long) :statuscode 403: 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 .......................................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "algorithm-C" } :query name: the name to validate :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json boolean used: true if the algorithm name is already used :>json string name: the full name (author/algorithm/version) :statuscode 200: No error :statuscode 403: Invalid credentials Updating an existing algorithm .............................. .. http:put:: /api/v1/algorithms/(author)/(algorithm)/ Updates an existing algorithm. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 400: Either parameters are missing or wrong (e.g. the short description is too long) :statuscode 403: Invalid credentials :statuscode 404: Request update to non-existing algorithm Deleting an existing algorithm .............................. .. http:delete:: /api/v1/algorithms/(author)/(algorithm)/ Deletes an existing algorithm. This does not return any object. **Example request**: .. sourcecode:: http DELETE /api/v1/algorithms/johndoe/algorithmA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 **Example response**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing algorithm Sharing an existing algorithm ............................. .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "status": "shared", } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string status: how the algorithm is shared :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing algorithm Comparing two algorithms ......................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ import numpy\n..." } :query fields: the name of the JSON fields to return. The declaration and the code are always returned by default. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string diff: a string containing all the differences between the various fields of the algorithm :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No algorithm with this name/version found .. _beatweb-webapi-libraryapi: Library API ----------- Retrieving a list of all the libraries accessible by the user ............................................................. .. http: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**: .. sourcecode:: http GET /api/v1/libraries/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 latest_versions: if true return only the latest version of each library :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string creation_date: date of creation of this library version :>jsonarr json declaration: the declaration, which includes a (short) description, the programming language, and the libraries that are used by this library. :>jsonarr string description: a description :>jsonarr string fork_of: parent library name if this object is a fork, null otherwise. :>jsonarr string hash: used to determine if two objects have the same content :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr boolean last_version: true if this object is the latest version :>jsonarr boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>jsonarr string name: object full name (author/library/version) :>jsonarr boolean opensource: true if this object is open source :>jsonarr integer previous_version: previous version, null otherwise :>jsonarr json sharing: information about how this library is shared :>jsonarr string short_description: a short description :>jsonarr integer version: object version number :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific library ............................. .. http:get:: /api/v1/libraries/(author)/(library)/ .. http: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**: .. sourcecode:: http GET /api/v1/library/johndoe/libraryA/1/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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)..." } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string accessibility: accessibility level (e.g. public, private etc.) :>json string code: the source code :>json string creation_date: date of creation of this library version :>json json declaration: the declaration, which includes a (short) description, the programming language, and the libraries that are used by this library. :>json string description: a description :>json string fork_of: parent library name if this object is a fork, null otherwise. :>json string hash: used to determine if two objects have the same content :>json boolean is_owner: true if the caller owns the object :>json boolean last_version: true if this object is the latest version :>json boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>json string name: object full name (author/library/version) :>json boolean opensource: true if this object is open source :>json integer previous_version: previous version, null otherwise :>json json sharing: information about how this library is shared :>json string short_description: a short description :>json integer version: its version number :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No algorithm with this name/version found Creating a new library ...................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http 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 name: the name of the library :query description: (optional) a description of the library :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :statuscode 201: No error :statuscode 400: Either parameters are missing or wrong (e.g. the name is already used) :statuscode 403: 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 ....................................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "library-C" } :query name: the name to validate :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json boolean used: true if the library name is already used :>json string name: sanitized library name :statuscode 200: No error :statuscode 400: either parameters are missing or wrong (e.g. the name is already used) :statuscode 403: invalid credentials Updating an existing library ............................ .. http:put:: /api/v1/libraries/(author)/(library)/ Updates an existing library. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 400: Either parameters are missing or wrong (e.g. the name is already used) :statuscode 403: Invalid credentials :statuscode 404: Request update to non-existing library Deleting an existing library ............................ .. http:delete:: /api/v1/libraries/(author)/(library)/ Deletes an existing library. This does not return any object. **Example request**: .. sourcecode:: http DELETE /api/v1/libraries/johndoe/libraryA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 **Example response**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing library Sharing an existing library ........................... .. http: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**: .. sourcecode:: http POST /api/v1/libraries/johndoe/libraryA/1/share/ Host: www.beat-eu.org/platform Authorization: Token 12345 { "users": ["jake", "anna"], "teams": ["rookies"] } **Example response**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "status": "shared", } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string status: how the library is shared :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing library Comparing two libraries ........................ .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ import numpy\n..." } :query fields: the name of the JSON fields to return. The declaration and the code are always returned by default. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string diff: a string containing all the differences between the various fields of the library :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No library with this name/version found .. _beatweb-webapi-toolchainapi: Toolchain API ------------- Retrieving a list of all the toolchains accessible by the user .............................................................. .. http: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**: .. sourcecode:: http GET /api/v1/toolchains/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 latest_versions: if true return only the latest version of each toolchain :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string creation_date: date of creation of this toolchain version :>jsonarr json declaration: the declaration, which includes a (short) description as well as the JSON declaration of the toolchain. :>jsonarr string description: a description. :>jsonarr string fork_of: parent toolchain name if this object is a fork, null otherwise. :>jsonarr string hash: used to determine if two objects have the same content :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr boolean last_version: true if this object is the latest version :>jsonarr boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>jsonarr string name: object full name (author/toolchain/version) :>jsonarr integer previous_version: previous version, null otherwise :>jsonarr json sharing: information about how this toolchain is shared :>jsonarr string short_description: a short description :>jsonarr integer version: object version number :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific toolchain ............................... .. http:get:: /api/v1/toolchains/(author)/(toolchain)/ .. http: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**: .. sourcecode:: http GET /api/v1/toolchains/johndoe/toolchainA/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 fields: the name of the JSON fields to return. The declaration is always returned by default. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string accessibility: accessibility level (e.g. public, private etc.) :>json json attestation: information about the attestation :>json string creation_date: date of creation of this toolchain version :>json json declaration: the declaration, which includes a (short) description as well as the JSON declaration of the toolchain. :>json boolean deletable: true if this object can be deleted :>json string description: a description. :>json string fork_of: parent toolchain name if this object is a fork, null otherwise. :>json string hash: used to determine if two objects have the same content :>json boolean is_owner: true if the caller owns the object :>json boolean last_version: true if this object is the latest version :>json boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>json string name: object full name (author/toolchain/version) :>json integer previous_version: previous version, null otherwise :>json json sharing: information about how this toolchain is shared :>json string short_description: a short description :>json integer version: its version number :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No toolchain with this name/version found Creating a new toolchain ........................ .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http 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 name: the name of the toolchain :query description: (optional) a description of the toolchain :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :statuscode 201: No error :statuscode 400: some required parameters are missing in the request :statuscode 403: 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 ......................................... .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "used": false, "name": "toolchain-C" } :query name: the name to validate :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :statuscode 200: No error :statuscode 400: Either parameters are missing or wrong :statuscode 403: Invalid credentials Updating an existing toolchain .............................. .. http:put:: /api/v1/toolchains/(author)/(toolchain)/ Updates an existing toolchain. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 200: No error :statuscode 400: Either parameters are missing or wrong (e.g. the short description is too long) :statuscode 403: Invalid credentials :statuscode 404: Request update to non-existing toolchain Deleting an existing toolchain .............................. .. http:delete:: /api/v1/toolchains/(author)/(toolchain)/ Deletes an existing toolchain. This does not return any object. **Example request**: .. sourcecode:: http DELETE /api/v1/algorithms/johndoe/toolchainA/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 **Example response**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing toolchain Sharing an existing toolchain ............................. .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json { "status": "shared", } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string status: how the toolchain is shared :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing toolchain Comparing two toolchains ........................ .. http: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**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json { "diff": "+ "inputA": ..." } :query fields: the name of the JSON fields to return. The declaration is always returned by default. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string diff: a string containing all the differences between the various fields of the toolchains. :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No toolchain with this name/version found .. _beatweb-webapi-experimentapi: Experiment API -------------- Retrieving a list of all the experiments accessible by the user ............................................................... .. http:get:: /api/v1/experiments/ .. http: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**: .. sourcecode:: http GET /api/v1/experiments/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 include_fields: the optional fields to include in the answer :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr boolean attestation_locked: tristate: if an attestation is associated, contains the lock state else null :>jsonarr string attestation_number: an attestation number if an attestation is associated, null otherwise :>jsonarr integer cputime: the cputime required to run this experiment :>jsonarr string creation_date: date of creation of this experiment :>jsonarr string data_read: amount of data read :>jsonarr string data_written: amount of data written :>jsonarr json datasets: the database datasets attached :>jsonarr string duration: the duration :>jsonarr string end_date: the end date :>jsonarr string fullname: object full name (author/toolchain_fullname/experiment_label) :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr string label: object label :>jsonarr boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>jsonarr string short_description: a short description :>jsonarr string start_date: the start date :>jsonarr string status: the experiment status such as Pending, Done, etc. :>jsonarr string toolchain: the attached toolchain :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific experiment ................................ .. http: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**: .. sourcecode:: http GET /api/v1/experiment/johndoe/johndoe/toolchainA/1/myexp/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 fields: the name of the JSON fields to return. :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json json configuration: the JSON configuration of the experiment :>json string description: a description :>json boolean done: true if the experiment has completed :>json boolean failed: true if the experiment has failed :>json json sharing: information about how this experiment is shared :>json string status: the status of the experiment :>json string short_description: a short description :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No experiment with this name/version found Creating a new experiment ......................... .. http:post:: /api/v1/experiments/(author)/ Creates a new experiment. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 201 CREATED Content-Type: application/json Location: http://www.beat-eu.org/api/v1/experiments/johndoe/johndoe/toolchainA/1/myexp2/ :reqheader Authorization: optional credentials for authentication :reqheader Content-Type: This should return ``application/json`` :json json results: the results of the experiment in a JSON object :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 404: No attestation with this number found .. _beatweb-webapi-databaseapi: Database API ------------ Retrieving a list of all the databases accessible by the user ............................................................. .. http: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**: .. sourcecode:: http GET /api/v1/databases/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 latest_versions: if true return only the latest versions of the database :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string creation_date: date of creation of this database version :>jsonarr json declaration: 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. :>jsonarr string description: a description. :>jsonarr string fork_of: parent database name if this object is a fork, null otherwise. :>jsonarr string hash: used to determine if two objects have the same content :>jsonarr boolean last_version: true if this object is the latest version :>jsonarr boolean modifiable: true if this object is still modifiable (i.e. not used by anything else) :>jsonarr string name: object full name (author/database/version) :>jsonarr integer nb_experiments: the number of experiments that use this database :>jsonarr integer nb_experiments_done: the number of completed experiments that use this database :>jsonarr integer previous_version: previous version, null otherwise :>jsonarr string short_description: a short description :>jsonarr integer version: object version number :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a list of all the database templates accessible by the user ...................................................................... .. http: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**: .. sourcecode:: http GET /api/v1/databases/templates/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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" ] }, ... } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific database .............................. .. http:get:: /api/v1/databases/(author)/(database)/ .. http: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**: .. sourcecode:: http GET /api/v1/databases/databaseA/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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 } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string accessibility: accessibility level (e.g. public, private etc.) :>json string code: the code of the corresponding database view :>json string creation_date: date of creation of this database version :>json json declaration: 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. :>json string description: a description. :>json string hash: used to determine if two objects have the same content :>json boolean last_version: true if this object is the latest version :>json string name: object full name (database/version) :>json integer nb_experiments: the number of experiments that use this database :>json integer nb_experiments_done: the number of completed experiments that use this database :>json integer previous_version: previous version, null otherwise :>json string short_description: a short description :>json integer version: its version number :statuscode 200: No error :statuscode 404: No database with this name/version found :statuscode 403: Invalid credentials .. note:: If the version number isn't specified, the latest accessible version of the database is returned. .. _beatweb-webapi-backendapi: Backend API ----------- Retrieving the scheduler (and workers) state ............................................ .. http: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**: .. sourcecode:: http GET /api/v1/backend/scheduler/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token Accept: */* **Example response**: .. sourcecode:: http 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 refresh: whether to retrieve information about the workers or to use the previously retrieved data. :reqheader Authorization: administrator credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json json cache: information about the cache, such as its capacity in MB, its number of free space. :>json json scheduler: 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 :>json json workers: information about the workers such as the amount of memory, the operating system or the environments available. :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 500: Could not connect to the scheduler, or the scheduler did not accept the request. Canceling all the experiments ............................. .. http:post:: /api/v1/backend/cancel-all-experiments/ This will cancel all the scheduled experiments. This does not return any object. **Example request**: .. sourcecode:: http POST /api/v1/backend/cancel-all-experiments/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token **Example response**: .. sourcecode:: http HTTP/1.0 200 OK :reqheader Authorization: administrator credentials for authentication :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 500: Could not connect to the scheduler, or the scheduler did not accept the request. Updating scheduler configuration ................................ .. http:post:: /api/v1/backend/queue-configuration/ This will update the scheduler configuration. This does not return any object. **Example request**: .. sourcecode:: http POST /api/v1/backend/queue-configuration/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 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**: .. sourcecode:: http HTTP/1.0 200 OK :reqheader Content-Type: This is ``application/json`` : nolist=0 **Example response**: .. sourcecode:: http HTTP/1.0 200 OK [ "ABCewQEQ", "ZRDFQQWD", ... ] :query 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. :query nolist: (Optional, default: 1) When 0, the Scheduler will return a list of the hashes of the removed files. :resheader 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. :reqheader Authorization: administrator credentials for authentication :statuscode 200: No error :statuscode 403: Invalid credentials :statuscode 500: 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 .............................................................. .. http: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**: .. sourcecode:: http POST /api/v1/backend/block-started/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 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**: .. sourcecode:: http HTTP/1.0 204 NO CONTENT :reqheader Content-Type: This is `application/json`. : 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**: .. sourcecode:: http HTTP/1.0 204 NO CONTENT :reqheader Content-Type: This is `application/json`. :jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string name: object name :>jsonarr json queues: 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). :>jsonarr string short_description: a short description :>jsonarr integer version: object version number :statuscode 200: No error :statuscode 403: Invalid credentials .. _beatweb-webapi-teamapi: Team API -------- Retrieving a list of all the teams accessible by a user ......................................................... .. http:get:: /api/v1/teams/ .. http: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**: .. sourcecode:: http GET /api/v1/teams/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http HTTP/1.0 200 OK Content-Type: application/json [ { "accessibility":"private", "is_owner": false, "name": "johndoe/does_team", "short_description": "John's example team" }, ... ] :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr string name: object name :>jsonarr string short_description: a short description :statuscode 200: No error :statuscode 403: Invalid credentials Retrieving a specific team .......................... .. http: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**: .. sourcecode:: http GET /api/v1/teams/johndoe/does_team/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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" } :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>json string accessibility: accessibility level (e.g. public, private etc.) :>json boolean is_owner: true if the caller owns the object :>json json members: the list of users belonging to this team :>json string name: object name :>json string short_description: a short description :statuscode 200: No error :statuscode 403: Invalid credentials Creating a new team ................... .. http:post:: /api/v1/teams/(author)/(team)/ Creates a new team. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 201 CREATED :reqheader Authorization: optional credentials for authentication :json string accessibility: accessibility level (e.g. public, private etc.) :json json members: the list of users belonging to this team :json string name: object name :json string short_description: a short description :statuscode 201: No error :statuscode 400: Either parameters are missing or wrong (e.g. the name is already used) :statuscode 403: Invalid credentials Updating an existing team ......................... .. http:put:: /api/v1/teams/(author)/(team)/ Updates an existing team. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK :reqheader Authorization: optional credentials for authentication :statuscode 200: No error :statuscode 400: Either parameters are missing or wrong (e.g. the name is already used) :statuscode 403: Invalid credentials :statuscode 404: Request update to non-existing team Deleting an existing team ......................... .. http:delete:: /api/v1/teams/(author)/(team)/ Deletes an existing team. This does not return any object. **Example request**: .. sourcecode:: http DELETE /api/v1/teams/johndoe/johns_team/1/ Host: www.beat-eu.org/platform Authorization: Token 12345 **Example response**: .. sourcecode:: http HTTP/1.1 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing team .. _beatweb-webapi-searchapi: Search API ---------- Retrieving a list of all searches accessible by the user ........................................................ .. http: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**: .. sourcecode:: http GET /api/v1/search/list/johndoe/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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" }, ... ] :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string accessibility: accessibility level (e.g. public, private etc.) :>jsonarr string author: the author :>jsonarr boolean is_owner: true if the caller owns the object :>jsonarr string name: object full name (author/search) :>jsonarr string user_name: object owner user name :statuscode 200: No error :statuscode 403: Invalid credentials Creating a new search ..................... .. http:post:: /api/v1/search/save/ Creates a new search. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 201 CREATED :reqheader Authorization: optional credentials for authentication :reqheader Content-Type: This should return ``application/json`` :json string status: how the search is shared :statuscode 200: no error :statuscode 403: Invalid credentials :statuscode 404: Request delete to non-existing search .. _beatweb-webapi-attestationapi: Attestation API --------------- Retrieving a list of all attestations of a given user ..................................................... .. http: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**: .. sourcecode:: http GET /api/v1/attestations/johndoe/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 Accept: */* **Example response**: .. sourcecode:: http 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" }, ... ] :reqheader Authorization: optional credentials for authentication :resheader Content-Type: This should return ``application/json`` :>jsonarr string creation_date: date of creation of this attestation version :>jsonarr string experiment: the label of the attested experiment :>jsonarr boolean locked: if true, the attestation is locked :>jsonarr integer nb_algorithms: the number of algorithms used by this attested experiment :>jsonarr integer nb_dataformats: the number of data formats used by this attested experiment :>jsonarr integer number: a number to uniquely identify this attestation :>jsonarr string publication_date: date of publication of this data attestation :>jsonarr string toolchain: the toolchain full name used by the attested experiment :statuscode 200: No error :statuscode 403: Invalid credentials Creating a new attestation .......................... .. http:post:: /api/v1/attestations/ Creates a new attestation. This does not return any object. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.0 201 CREATED :query experiment: the full name of the experiment to attest :reqheader Authorization: optional credentials for authentication :statuscode 201: no error :statuscode 400: some required parameters are missing or wrong in the request OR experiment is already attested :statuscode 403: 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 ........................ .. http:post:: /api/v1/attestations/unlock/(int: attestation_number)/ Unlocks an attestation. This does not return any object. **Example request**: .. sourcecode:: http POST /api/v1/attestations/unlock/2004723460/ HTTP/1.1 Host: www.beat-eu.org/platform Authorization: Token 12345 **Example response**: .. sourcecode:: http HTTP/1.0 204 NO CONTENT :reqheader Authorization: optional credentials for authentication :statuscode 204: no error :statuscode 400: Either parameters are missing or wrong OR the attestation is already unlocked :statuscode 403: Invalid credentials