4. API¶
The provisioning API is available through HTTP calls. Authentication is
handled by JSON Web Tokens (JWT) for all calls except permission_responses.
Both the DAS and the calling application need to know a shared secret,
JWT_SECRET_KEY in the configuration file.
The following JWT attributes need to be present in the payload:
{
"iss": "mgrid",
"iat": 1532007679,
"jti": "9deb0180-8a0f-4c12-b6d4-1841d357f04b",
"identity": "name_of_calling_application",
"type": "access",
"fresh": "True"
}
Where iat is the number of seconds since epoch and jti is a nonce,
e.g. a UUID.
This payload then needs to be signed with the shared secret and added as the
Authorization HTTP header. In a Python program this can be performed as
such:
token = jwt.encode(payload, jwt_secret_key, algorithm="HS512")
http_header = {"Authorization": "Bearer %s" % token}
4.1. Datasets¶
4.1.1. /api/v1/datasets GET¶
List all known datasets.
Input: None
Output
[
{
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"name": "dataset1",
"id": 1
},
{
"uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
"name": "dataset2",
"id": 2
}
]
4.1.2. /api/v1/datasets POST¶
Create a new dataset. Note that uuid must be unique among all datasets.
Input
{
"name": "dataset1",
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c"
}
Output
{
"name": "dataset1",
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"id": 1
}
4.1.3. /api/v1/datasets/{id} GET¶
List a specific dataset by identifier.
Input: Dataset identifier in the URL
Output
{
"name": "dataset1",
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"id": 1
}
4.1.4. /api/v1/datasets/{id} DELETE¶
Delete a specific dataset by identifier.
Input: Dataset identifier in the URL
Output
{
"code": 200,
"status": "Deleted",
"message": "Dataset successfully deleted"
}
4.1.5. /api/v1/datasets/by_uuid/{uuid} GET¶
List a specific dataset by UUID.
Input: UUID in the URL
Output
{
"name": "dataset1",
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"id": 1
}
4.2. Users¶
4.2.1. /api/v1/users GET¶
List all known users.
Input: None
Output
[
{
"email": "user1@example.com",
"name": "user1",
"id": 1
},
{
"email": "user2@example.com",
"name": "user2",
"id": 2
}
]
4.2.2. /api/v1/users POST¶
Create a new user. Note that email must be unique among all users.
Input
{
"name": "user1",
"email": "user1@example.com"
}
Output
{
"name": "user1",
"email": "user1@example.com",
"id": 1
}
4.2.3. /api/v1/users/{id} GET¶
List a specific user by identifier.
Input: User identifier in the URL
Output
{
"email": "user1@example.com",
"name": "user1",
"id": 1
}
4.2.4. /api/v1/users/{id} DELETE¶
Delete a specific user by identifier.
Input: User identifier in the URL
Output
{
"code": 200,
"status": "Deleted",
"message": "User successfully deleted"
}
4.2.5. /api/v1/users/by_email/{email} GET¶
List a specific user by email address.
Input: Email address in the URL
Output
{
"email": "user1@example.com",
"name": "user1",
"id": 1
}
4.3. Approvers¶
4.3.1. /api/v1/approvers GET¶
List all known approvers.
Input: None
Output
[
{
"operation": "view",
"dataset": {
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"name": "dataset1",
"id": 1
},
"user": {
"email": "user1@example.com",
"name": "user1",
"id": 1
},
"id": 1
},
{
"operation": "transfer",
"dataset": {
"uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
"name": "dataset2",
"id": 2
},
"user": {
"email": "user1@example.com",
"name": "user1",
"id": 1
},
"id": 2
}
]
4.3.2. /api/v1/approvers POST¶
Create a new approver.
Input
{
"dataset_id": 2,
"user_id": 1,
"operation": "transfer"
}
Output
{
"operation": "transfer",
"dataset": {
"uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
"name": "dataset2",
"id": 2
},
"user": {
"email": "user1@example.com",
"name": "user1",
"id": 1
},
"id": 2
}
4.3.3. /api/v1/approvers/{id} GET¶
List a specific approver by identifier.
Input: Approver identifier in the URL
Output
{
"operation": "transfer",
"dataset": {
"uuid": "258e431f-9a36-4687-a1da-5c5426eb953c",
"name": "dataset2",
"id": 2
},
"user": {
"email": "user1@example.com",
"name": "user1",
"id": 1
},
"id": 2
}
4.3.4. /api/v1/approvers/{id} DELETE¶
Delete a specific approver by identifier.
Input: Approver identifier in the URL
Output
{
"code": 200,
"status": "Deleted",
"message": "Approver successfully deleted"
}
4.5. Permission Requests¶
4.5.1. /api/v1/permission_requests GET¶
List all known permission requests.
Input: None
Output
[
{
"denied_message": "Message shown to user if request is denied",
"operation": "transfer",
"user": {
"id": 1,
"email": "user1@example.com",
"name": "user1"
},
"details": {"reason": "Details of the permission prequest"},
"approved_message": "Message shown to user if request is approved",
"dataset": {
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"id": 1,
"name": "dataset1"
},
"context": "123456789",
"id": 2,
"approved": false,
"denied": false
}
]
4.5.2. /api/v1/permission_requests POST¶
Create a new permission request.
Input
{
"user_email": "user1@example.com",
"operation": "transfer",
"dataset_uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"details": {"reason": "Details of the permission request"},
"approved_message": "Message shown to user if request is approved",
"denied_message": "Message shown to user if request is denied",
"context": "123456789"
}
Output
{
"id": 2
}
4.5.3. /api/v1/permission_requests/{id} GET¶
List a specific permission request by identifier.
Input: Permission request identifier in the URL
Output
{
"denied_message": "Message shown to user if request is denied",
"operation": "transfer",
"user": {
"id": 1,
"email": "user1@example.com",
"name": "user1"
},
"details": {"reason": "Details of the permission request"},
"approved_message": "Message shown to user if request is approved",
"dataset": {
"uuid": "3cc7afb5-e873-482e-bc32-ce914c7c1c2c",
"id": 1,
"name": "dataset1"
},
"context": "123456789",
"id": 2,
"approved": false,
"denied": false
}
4.5.4. /api/v1/permission_requests/{id} DELETE¶
Delete a specific permission request by identifier.
Input: Permission request identifier in the URL
Output
{
"code": 200,
"status": "Deleted",
"message": "Permission request successfully deleted"
}
4.5.5. /api/v1/permission_requests/search GET¶
Search for permission requests by user email, operation and/or dataset UUID.
Input: Permission request parameters in JSON body
{
"user_email": "user1@example.com",
"operation": "transfer",
"dataset_uuid": "9ccd087e-f70c-4c4e-b0e7-4a46d67e99e0"
}
Output
[
{
"user_email": "user1@example.com",
"operation": "transfer",
"dataset_uuid": "9ccd087e-f70c-4c4e-b0e7-4a46d67e99e0",
"context": "123456789"
}
]
4.6. Permission Responses¶
4.6.1. /api/v1/permission_responses/{id}/{decision} GET¶
This HTTP call is provided for users to either approve or deny a permission request. The user needs to be logged in to perform this action. If the user is not yet logged in, the login page is shown. No JWT token is needed.
Input: Permission request identifier and decision (‘approve’ or ‘deny’) in the URL.
Output: The user is shown a list of permission requests and previous responses.
4.7. Allowed Operations¶
4.7.1. /api/v1/allowed_operations/{dataset_uuid}/{user_email} GET¶
List allowed operations of a specific user for a dataset.
Input: Dataset UUID and user email in the URL
Output
{
"transfer": "123456789"
}
4.7.2. /api/v1/multiple_allowed_operations/{dataset_uuid}/{user_email} GET¶
List allowed operations of a specific user for a dataset, and enumerate all possible contexts.
Input: Dataset UUID and user email in the URL
Output
{
"transfer": ["123456789", "some other context"]
}