From 0a019f94df0b5dff999e536c9aa64fc70055c948 Mon Sep 17 00:00:00 2001 From: Ninad Bhat Date: Mon, 3 May 2021 12:05:10 +1000 Subject: [PATCH 1/2] Adds AEP for extending API --- 006_extend_restapi/readme.md | 175 +++++++++++++++++++++++++++++++++++ README.md | 5 +- 2 files changed, 178 insertions(+), 2 deletions(-) create mode 100644 006_extend_restapi/readme.md diff --git a/006_extend_restapi/readme.md b/006_extend_restapi/readme.md new file mode 100644 index 0000000..a39c828 --- /dev/null +++ b/006_extend_restapi/readme.md @@ -0,0 +1,175 @@ +# Extending the AiiDA REST API + +| AEP number | 006 | +|------------|------------------------------------------------------------------| +| Title | Extending the AiiDA REST API towards workflow management | +| Authors | [Ninad Bhat](mailto:bhat.ninadmb@gmail.com) (NinadBhat) | +| Champions | [Leopold Talirz](mailto:leopold.talirz@epfl.ch) (Italirz) | +| Type | S - Standard | +| Created | 27-April-2021 | +| Status | draft | + + +## Background + +AiiDA comes with a built-in REST API (based on the flask microframework) that provides access to the provenance graph stored automatically with any workflow execution. In order to enable the integration of AiiDA as a workflow backend into new or existing web platforms, we plan to extend the REST API to support workflow management. + +## Proposed Enhancement + +The Proposal is to make three additions to AiiDA REST API. + +1. Add JSON schema validation and implementing authorisation +2. Add POST methods to /users, /computers, /nodes and /groups endpoint +3. Creating a new /processes endpoint + + +## Detailed Explanation + +### Schema Validation and Authorisation +Currently, only QueryBuilder endpoint has a post method. Post endpoint for QueryBuilder was implemented in [PR #4337](https://github.com/aiidateam/aiida-core/pull/4337). The current implementation only checks if the posted JSON is a dict at [L269](https://github.com/aiidateam/aiida-core/blob/develop/aiida/restapi/resources.py#L269). +Adding a JSON Schema Validation has the following advantages: +- Standardise the input format required +- Better error messages when invalid post requests are made + +The post method will allow users to edit AiiDA entities. Hence, it is essential to verify if the user has the relevant authorisations to make the changes. + +### Post methods +The post endpoints will be implemented in the following order: + +1. /users +2. /computers +3. /groups +4. /nodes + +The JSOC Schema for the endpoint is: + +#### 1. /users + +``` + + { + "first_name": { + "description": "First Name of the user", + "type": "string" + }, + "last_name": { + "description": "Last Name of the user", + "type": "string" + }, + "institution": { + "description": "Name of the institution", + "type": "string" + }, + "email": { + "description": "Email Address of the User", + "type": "string" + } + } +``` + +#### 2. /computers + +``` + + { + "name": { + "description": "Used to identify a computer. Must be unique.", + "type": "string" + }, + "hostname": { + "description": "Label that identifies the computer within the network.", + "type": "string" + }, + "scheduler_type": { + "description": "Information of the scheduler (and plugin) that the computer uses to manage jobs.", + "type": "string" + }, + "transport_type": { + "description": "information of the transport (and plugin) required to copy files and communicate to and from the computer.", + "type": "string" + }, + "metadata": { + "description": "General settings for these communication and management protocols." + "type": "string" + }, + } + + +``` + +#### 3. /groups +``` + + { + "label": { + "description": "Used to access the group. Must be unique" + "type": "string" + }, + "type_string": { + "description": "" + "type": "string" + }, + "user_id": { + "description": "Id of users in the group." + "type": "string" + }, + } + +``` + + +#### 4. /nodes + +``` +[ + node1: + { + "node_type": { + "description": "Type of data the node is" + "type": "string" + }, + "process_type": { + "description": "Specific plugin the node uses" + "type": "string" + } + "attributes": { + "description": "attributes of the node" + "type": "json object" + }, + "extras": { + "description": "" + "type": "json object" + }, + "user_id": { + "description": "Id of the user creating the node." + "type": "string" + }, + "computer_id": { + "description": "Id of computer associated with the node." + "type": "string" + } + + } + node2: + { + ... + } + + +] + + +``` + +### Adding /processes endpoint +The /processes will allow access to current processes and also addition of new processes through GET and POST methods, respectively. + +## Pros and Cons + +### Pros +1. Will allow workflow management AiiDA REST API through process endpoint +2. Should enable integration of AiiDA workflows into generic web platforms + +### Cons +1. Development time spent on extending API +2. Also the time spent on maintaining API diff --git a/README.md b/README.md index f35d56a..1374b79 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The purpose is to publicly discuss new features & design choices in the AiiDA ecosystem and to document the decision making process. -## Index of AEPs +## Index of AEPs | Number | Status | Title | |--------|------------------|------------------------------------------------------------------| @@ -19,6 +19,7 @@ ecosystem and to document the decision making process. | 002 | implemented | [AiiDA Dependency Management](002_dependency_management/) | | 003 | active | [Adopt NEP 29](003_adopt_nep_29/) | | 005 | draft | [New Export Format](005_exportformat/) | +| 006 | draft | [Extend REST API](006_entend_restapi/) | ## Submitting an AEP -The submission process is described in the [AEP guidelines](000_aep_guidelines/readme.md) which also act as a template for new AEPs. +The submission process is described in the [AEP guidelines](000_aep_guidelines/readme.md) which also act as a template for new AEPs. From a695e17737e848a7aefcc67b92a831275722aa7a Mon Sep 17 00:00:00 2001 From: Ninad Bhat Date: Sat, 8 May 2021 22:52:38 +1000 Subject: [PATCH 2/2] Review changes --- 006_extend_restapi/readme.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/006_extend_restapi/readme.md b/006_extend_restapi/readme.md index a39c828..1fb14f3 100644 --- a/006_extend_restapi/readme.md +++ b/006_extend_restapi/readme.md @@ -4,7 +4,7 @@ |------------|------------------------------------------------------------------| | Title | Extending the AiiDA REST API towards workflow management | | Authors | [Ninad Bhat](mailto:bhat.ninadmb@gmail.com) (NinadBhat) | -| Champions | [Leopold Talirz](mailto:leopold.talirz@epfl.ch) (Italirz) | +| Champions | [Leopold Talirz](mailto:leopold.talirz@epfl.ch) (ltalirz) | | Type | S - Standard | | Created | 27-April-2021 | | Status | draft | @@ -18,19 +18,23 @@ AiiDA comes with a built-in REST API (based on the flask microframework) that pr The Proposal is to make three additions to AiiDA REST API. -1. Add JSON schema validation and implementing authorisation -2. Add POST methods to /users, /computers, /nodes and /groups endpoint -3. Creating a new /processes endpoint +1. Add validation of the QueryBuilder JSON using JSON schema +2. Add authentication/authorisation +3. Add POST methods to /users, /computers, /nodes and /groups endpoints +4. Add a new /processes endpoint ## Detailed Explanation -### Schema Validation and Authorisation -Currently, only QueryBuilder endpoint has a post method. Post endpoint for QueryBuilder was implemented in [PR #4337](https://github.com/aiidateam/aiida-core/pull/4337). The current implementation only checks if the posted JSON is a dict at [L269](https://github.com/aiidateam/aiida-core/blob/develop/aiida/restapi/resources.py#L269). +### Schema Validation +Currently, only the `/querybuilder` endpoint accepts `POST` requests (implemented in [PR #4337](https://github.com/aiidateam/aiida-core/pull/4337)). +The current implementation only checks if the posted JSON is a `dict` (see [L269](https://github.com/aiidateam/aiida-core/blob/develop/aiida/restapi/resources.py#L269)). + Adding a JSON Schema Validation has the following advantages: - Standardise the input format required - Better error messages when invalid post requests are made +### Authorisation The post method will allow users to edit AiiDA entities. Hence, it is essential to verify if the user has the relevant authorisations to make the changes. ### Post methods @@ -41,7 +45,7 @@ The post endpoints will be implemented in the following order: 3. /groups 4. /nodes -The JSOC Schema for the endpoint is: +Below, we provide JSON schemas for validating `POST` requests to these endpoints: #### 1. /users @@ -134,11 +138,11 @@ The JSOC Schema for the endpoint is: } "attributes": { "description": "attributes of the node" - "type": "json object" + "type": "object" }, "extras": { "description": "" - "type": "json object" + "type": "object" }, "user_id": { "description": "Id of the user creating the node." @@ -172,4 +176,6 @@ The /processes will allow access to current processes and also addition of new p ### Cons 1. Development time spent on extending API -2. Also the time spent on maintaining API +2. Increased maintenance effort for the REST API for changes in the ORM + +The second point could be minimized by aiming for a single source for the attributes of the ORM entities that is used both by the python API and the REST API.