WIP Overhaul of ELIXIR Permissions API specification

README.md

@@ -61,22 +61,24 @@ For more technical details, consult the [API Specification](https://app.swaggerh
 curl -X POST \
   http://localhost:8080/user \
   -H 'Content-Type: application/json' \
+  -H 'elixir-api-key: secret' \
   -d '{
-  "user_identifier": "test_user",
-  "affiliation": "",
-  "datasets": [
+  "userDetails": {
+    "elixirId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org",
+    "eduPersonPrincipalName": "user@org.org",
+    "userEmail": "firstname.lastname@organisation.org",
+    "realName": "Firstname Lastname"
+  },
+  "datasetPermissions": [
     {
-      "permissions": [
-        {
-          "affiliation": "example-org",
-          "source_signature": "",
-          "url_prefix": "",
-          "datasets": [
-            "urn:example-dataset-1",
-            "urn:example-dataset-2"
-          ]
-        }
-      ]
+      "datasetId": "urn:example-dataset-1",
+      "startDate": "2018-01-01 12:00:00.000000+0000",
+      "endDate": "2019-01-01 12:00:00.000000+0000"
+    },
+    {
+      "datasetId": "urn:example-dataset-2",
+      "startDate": "",
+      "endDate": ""
     }
   ]
 }'
@@ -85,30 +87,21 @@ curl -X POST \
 #### GET /user/username
 `GET` method at `/user` endpoint is used to fetch dataset permissions for user.
 ```
-curl -X GET http://localhost:8080/user/test_user
+curl -X GET -H 'elixir-api-key: secret' http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org
 ```
 
 #### PATCH /user/username
-`PATCH` method at `/user` endpoint is used to update dataset permissions for user.
+`PATCH` method at `/user` endpoint is used to update user details and dataset permissions for user. `PATCH` endpoint consumes the same schema as `POST` endpoint, but all fields are optional instead of mandatory.
 ```
 curl -X PATCH \
-  http://localhost:8080/user/test_user \
+  http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org \
   -H 'Content-Type: application/json' \
+  -H 'elixir-api-key: secret' \
   -d '{
-  "user_identifier": "",
-  "affiliation": "",
-  "datasets": [
+  "datasetPermissions": [
     {
-      "permissions": [
-        {
-          "affiliation": "example-org",
-          "source_signature": "",
-          "url_prefix": "",
-          "datasets": [
-            "urn:example-dataset-3"
-          ]
-        }
-      ]
+      "datasetId": "urn:example-dataset-1",
+      "endDate": "2020-01-01 12:00:00.000000+0000"
     }
   ]
 }'
@@ -117,10 +110,5 @@ curl -X PATCH \
 #### DELETE /user/username
 `DELETE` method at `/user` endpoint is used to delete user along with dataset permissions.
 ```
-curl -X DELETE http://localhost:8080/user/test_user
+curl -X DELETE -H 'elixir-api-key: secret' http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org
 ```
-
-</details>
-
-### Other Business
-The [Permissions API Specification](https://app.swaggerhub.com/apis-docs/ELIXIR-Finland/Permissions/1.2) contains some typos. A [suggestions](suggestions.md) document has been drafted to correct those issues. Expect changes to be made to the specification in the near future, along with changes to the API app.

docs/example.rst

@@ -31,26 +31,25 @@ An example ``POST`` request and response to the ``user`` endpoint:
 
 .. code-block:: console
 
-  $ curl -X POST \
+  curl -X POST \
     http://localhost:8080/user \
     -H 'Content-Type: application/json' \
     -H 'elixir-api-key: secret' \
     -d '{
-    "user_identifier": "test_user",
-    "affiliation": "",
-    "datasets": [
+    "userDetails": {
+      "elixirId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org",
+      "eduPersonPrincipalName": "username@organisation.org",
+      "userEmail": "firstname.lastname@organisation.org",
+      "realName": "Firstname Lastname"
+    },
+    "datasetPermissions": [
       {
-        "permissions": [
-          {
-            "affiliation": "example-org",
-            "source_signature": "",
-            "url_prefix": "",
-            "datasets": [
-              "urn:example-dataset-1",
-              "urn:example-dataset-2"
-            ]
-          }
-        ]
+        "datasetId": "urn:example-dataset-1",
+        "startDate": "2018-01-01 12:00:00.000000+0000",
+        "endDate": "2019-01-01 12:00:00.000000+0000"
+      },
+      {
+        "datasetId": "urn:example-dataset-2",
       }
     ]
   }'
@@ -65,58 +64,81 @@ An example ``GET`` request and response to the ``user`` endpoint:
 
 .. code-block:: console
 
-  $ curl -X GET -H 'elixir-api-key: secret' http://localhost:8080/user/test_user
+  $ curl -X GET -H 'elixir-api-key: secret' http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org
 
 Example Response:
 
 .. code-block:: javascript
 
   {
-    "permissions": [
-        {
-            "affiliation": "",
-            "source_signature": "",
-            "url_prefix": "",
-            "datasets": [
-                "urn:example-dataset-1",
-                "urn:example-dataset-2"
-            ]
-        }
+    "sourceSignature": "string",
+    "datasetPermissions": [
+      {
+        "userAffiliation": "username@organisation.org",
+        "urlPrefix": "",
+        "datasetId": "urn:example-dataset-1",
+        "startDate": "2018-01-01 12:00:00.000000+0000",
+        "endDate": "2019-01-01 12:00:00.000000+0000"
+      },
+      {
+        "datasetOwner": "example-org",
+        "urlPrefix": "",
+        "datasetId": "urn:example-dataset-2",
+        "startDate": "2018-11-06 12:00:00.000000+0000",
+        "endDate": "None"
+      }
     ]
   }
 
-An example ``PATCH`` request and response to the ``user`` endpoint:
+Few examples of ``PATCH`` requests to the ``user`` endpoint:
+
+CASE 1: Update dataset permissions
 
 .. code-block:: console
 
-  $ curl -X PATCH \
-    http://localhost:8080/user/test_user \
+  curl -X PATCH \
+    http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org \
     -H 'Content-Type: application/json' \
     -H 'elixir-api-key: secret' \
     -d '{
-    "user_identifier": "",
-    "affiliation": "",
-    "datasets": [
+    "datasetPermissions": [
       {
-        "permissions": [
-          {
-            "affiliation": "example-org",
-            "source_signature": "",
-            "url_prefix": "",
-            "datasets": [
-              "urn:example-dataset-3"
-            ]
-          }
-        ]
+        "datasetId": "urn:example-dataset-1",
+        "endDate": "2020-01-01 12:00:00.000000+0000"
       }
     ]
   }'
 
-Example Response:
+CASE 2: Clear dataset permissions by sending an empty ``datasetPermissions`` object
 
-.. code-block:: text
+.. code-block:: console
 
-  Successful operation
+  curl -X PATCH \
+    http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org \
+    -H 'Content-Type: application/json' \
+    -H 'elixir-api-key: secret' \
+    -d '{
+    "datasetPermissions": [{}]
+  }'
+
+CASE 3: Update user details
+
+.. code-block:: console
+
+  curl -X PATCH \
+    http://localhost:8080/user/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@elixir-europe.org \
+    -H 'Content-Type: application/json' \
+    -H 'elixir-api-key: secret' \
+    -d '{
+    "userDetails": {
+      "userEmail": "user.name@organisation.org",
+      "realName": "User Name"
+    }
+  }'
+
+.. note:: ``PATCH`` endpoint consumes the same schema as ``POST`` endpoint, but all fields are optional instead of mandatory.
+
+.. note:: Successful ``PATCH`` requests respond with ``HTTP 204 No Content``.
 
 An example ``DELETE`` request and response to the ``user`` endpoint:
 

docs/instructions.rst

@@ -9,25 +9,23 @@ Environment Setup
 The application requires some environmental arguments in order to run properly, these are illustrated in
 the table below.
 
-+------------- +-------------------------------+-------------------------------------+
-| ENV          | Default                       | Description                         |
-+------------- +-------------------------------+-------------------------------------+
-| `DB_HOST`    | `postgresql://localhost:5432` | The URL for the PostgreSQL server.  |
-+------------- +-------------------------------+-------------------------------------+
-| `DB_NAME`    | `rems`                        | Name of the database.               |
-+------------- +-------------------------------+-------------------------------------+
-| `DB_USER`    | `rems`                        | Database username.                  |
-+------------- +-------------------------------+-------------------------------------+
-| `DB_PASS`    | `rems`                        | Database password.                  |
-+------------- +-------------------------------+-------------------------------------+
-| `APP_HOST`   | `0.0.0.0`                     | Default Host for the Web Server.    |
-+------------- +-------------------------------+-------------------------------------+
-| `APP_PORT`   | `8080`                        | Default port for the Web Server.    |
-+------------- +-------------------------------+-------------------------------------+
-| `PUBLIC_KEY` | `None`                        | Mandatory api key.                  |
-+------------- +-------------------------------+-------------------------------------+
-| `DEBUG`      | `True`                        | If set to `True`, logs all actions. |
-+------------- +-------------------------------+-------------------------------------+
++-------------+-------------------------------+-----------------------------------------------+
+| ENV         | Default                       | Description                                   |
++-------------+-------------------------------+-----------------------------------------------+
+| `DB_HOST`   | `postgresql://localhost:5432` | The URL for the PostgreSQL server.            |
++-------------+-------------------------------+-----------------------------------------------+
+| `DB_NAME`   | `rems`                        | Name of the database.                         |
++-------------+-------------------------------+-----------------------------------------------+
+| `DB_USER`   | `rems`                        | Database username.                            |
++-------------+-------------------------------+-----------------------------------------------+
+| `DB_PASS`   | `rems`                        | Database password.                            |
++-------------+-------------------------------+-----------------------------------------------+
+| `APP_HOST`  | `0.0.0.0`                     | Default Host for the Web Server.              |
++-------------+-------------------------------+-----------------------------------------------+
+| `APP_PORT`  | `8080`                        | Default port for the Web Server.              |
++-------------+-------------------------------+-----------------------------------------------+
+| `DEBUG`     | `False`                       | If set to any string value, logs all actions. |
++-------------+-------------------------------+-----------------------------------------------+
 
 Setting the necessary environment variables can be done  e.g. via the command line:
 
@@ -39,7 +37,6 @@ Setting the necessary environment variables can be done  e.g. via the command li
     $ export DB_PASS=rems
     $ export HOST=0.0.0.0
     $ export PORT=8080
-    $ export PUBLIC_KEY=secret_string
     $ export DEBUG=True
 
 .. _app-setup:

elixir_rems_proxy/app.py

@@ -31,12 +31,10 @@ async def user_post(request):
     LOG.debug('POST Request received.')
     db_pool = request.app['pool']
 
-    missing_datasets = await process_post_request(request, db_pool)
+    processed_request = await process_post_request(request, db_pool)
 
-    if len(missing_datasets) == 0:
+    if processed_request:
         return web.HTTPOk(text='Successful operation')
-    else:
-        return web.HTTPCreated(text=f'Following datasets are missing from REMS ({missing_datasets}), check "GET /user" endpoint for added permissions')
 
 
 @routes.get('/user/')
@@ -47,16 +45,9 @@ async def user_get(request):
     List all datasets user has access to.
     """
     LOG.debug('GET Request received.')
-    user_identifier = None  # username in REMS
+    user_identifier = None  # ELIXIR id == REMS userid
     db_pool = request.app['pool']
 
-    # try:
-    #     # Optional query parameter, retrieved from /user/{user}?user_affiliation={organisation}
-    #     # user_affiliation = request.query['user_affiliation']  # NOT IN USE
-    # except KeyError as key_error:
-    #     LOG.debug(f'KeyError at optional key {key_error}, ignore and pass.')
-    #     pass
-
     if 'user' in request.match_info:
         user_identifier = request.match_info['user']
         processed_request = await process_get_request(user_identifier, db_pool)
@@ -72,18 +63,16 @@ async def user_get(request):
 async def user_patch(request):
     """PATCH request to the /user endpoint.
 
-    Update dataset permissions for given user.
+    Update user details or dataset permissions for given user.
     """
     LOG.debug('PATCH Request received.')
     db_pool = request.app['pool']
 
     if 'user' in request.match_info:
         user_identifier = request.match_info['user']
         processed_request = await process_patch_request(user_identifier, request, db_pool)
-        if len(processed_request) == 0 or processed_request is True:
-            return web.HTTPOk(text='Successful operation')
-        else:
-            return web.HTTPCreated(text=f'Following datasets are missing from REMS ({processed_request}), check "GET /user" endpoint for permissions')
+        if processed_request:
+            return web.HTTPNoContent()
     else:
         raise web.HTTPBadRequest(text='Username not provided')
 
@@ -96,7 +85,7 @@ async def user_delete(request):
     Delete user.
     """
     LOG.debug('DELETE Request received.')
-    user_identifier = None  # username in REMS
+    user_identifier = None  # ELIXIR id == REMS userid
     db_pool = request.app['pool']
 
     if 'user' in request.match_info: