AEP: extending the REST API to support mutating (POST) queries #24
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,181 @@ | ||
| # Extending the AiiDA REST API | ||
|
|
||
| | AEP number | 006 | | ||
| |------------|------------------------------------------------------------------| | ||
| | Title | Extending the AiiDA REST API towards workflow management | | ||
| | Authors | [Ninad Bhat](mailto:[email protected]) (NinadBhat) | | ||
| | Champions | [Leopold Talirz](mailto:[email protected]) (ltalirz) | | ||
| | 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 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 | ||
| 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 | ||
| The post endpoints will be implemented in the following order: | ||
|
|
||
| 1. /users | ||
| 2. /computers | ||
| 3. /groups | ||
| 4. /nodes | ||
|
|
||
| Below, we provide JSON schemas for validating `POST` requests to these endpoints: | ||
|
|
||
| #### 1. /users | ||
|
|
||
| ``` | ||
|
|
||
| { | ||
| "first_name": { | ||
|
There was a problem hiding this comment. You might want/need to add some extra metadata around I would have thought more something like {
"$id": "https://raw.githubusercontent.com/aiidateam/aiida-core/master/aiida/restapi/schemas/user.schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "User",
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "The person's 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": "object" | ||
| }, | ||
| "extras": { | ||
| "description": "" | ||
| "type": "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. 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. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Most of this information already exists in the translators
https://github.com/aiidateam/aiida-core/blob/5f50f0335761386ddacbb5de4a6934b659b20e2d/aiida/restapi/translator/user.py#L40-L69
We should reuse this, i.e. either generate the JSON schema from the
projectable_propertiesor vice versa (to think about).Furthermore, the JSON schema should contain the "required" field with information on whether each of the respective fields