PhenoTips » Developer Guide » API » Permissions RESTful API

Permissions RESTful API

This page is a draft.

Starting with version 1.3 Milestone 2 PhenoTips provides a RESTful API ability to manage patient record's permission.

The REST services allow retrieving and updating patient record's permissions, ownership, global visibility and collaborators.

Data is exchanged in JSON format. 

For details regarding accessing the service, authentication, command-line tools and browser extensions please refer to the main API document.

Permissions resources

/patients/{id}/permissions

  • HTTP method: GET

    Media types:
    application/json, application/xml
    Result:
    Retrieves all permissions: owner, collaborators, visibility
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found, either the patient doesn't exist or the permissions module is not installed
  • HTTP method: PATCH

    Accepted Media types:
    application/json, application/x-www-form-urlencoded
    Media types:
    application/json, application/xml
    Result:
    Updates the permissions on a specified level (owner, global visibility, collaborators)  
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized
    404 if the resource was not found
  • HTTP Method: PUT

    Accepted Media type:
    application/json
    Media types:
    application/json, application/xml
    Result:
    Updates the permissions for a patient record, identified by its internal PhenoTips identifier, from its JSON representation. If the indicated patient record doesn't exist, if the JSON does not contain all the required fields (i.e. owner, visibility), or if the user sending the request doesn't have the right to modify it, no change is performed and an error is returned. Note: the permissions are completely replaced with the data in the JSON.
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

/patients/{id}/permissions/owner

  • HTTP method: GET

    Media types:
    application/json, application/xml
    Result:
    Retrieves information about the owner
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found
  • HTTP method: PUT

    Accepted Media types:
    application/json, application/x-www-form-urlencoded
    Media types:
    application/json, application/xml
    Result:
    Updates the owner
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

/patients/{id}/permissions/visibility

  • HTTP method: GET

    Media types:
    application/json, application/xml
    Result:
    Retrieves information about the visibility (hidden, public, private, open, matchable)
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found
  • HTTP method: PUT

    Accepted Media type:
    application/json
    Media types:
    application/json, application/xml
    Result:
    Updates visibility
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

/patients/{id}/permissions/collaborators

  • HTTP method: GET

    Media types:
    application/json, application/xml
    Result:
    Retrieves information about the collaborators
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found
  • HTTP method: PATCH

    Accepted Media types:
    application/json, application/x-www-form-urlencoded
    Media types:
    application/json, application/xml
    Result:
    Adds a new collaborator, or updates the permission level of a collaborator
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized
    404 if the resource was not found
  • HTTP method: PUT

    Accepted Media type:
    application/json
    Media types:
    application/json, application/xml
    Result:
    Updates all collaborators (all previous collaborators are replaced with this information)
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found
  • HTTP method: DELETE

    Media types:
    application/json, application/xml
    Result:
    Deletes all collaborators
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

/patients/{id}/permissions/collaborators/{id}

  • HTTP method: GET

    Media types:
    application/json, application/xml
    Result:
    Retrieves information about the specified collaborator
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found
  • HTTP method: DELETE

    Media types:
    application/json, application/xml
    Result:
    Deletes a collaborator
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

Testing resource URIs

Retrieve patient record's permissions

HTTP method: GET
URL: http://localhost:8088/rest//patients/{id}/permissions

For an existing patient record with an id value of P0000008, replace {id} in the url with P0000008.

Example curl request:

curl -H "Content-Type: application/json" -X GET http://localhost:8088/rest/patients/P0000008/permissions

Example response body:

{
"links": [{
"allowedMethods": ["GET", "PUT", "PATCH"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions",
"rel": "self"
}, {
"allowedMethods": ["GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/owner",
"rel": "https://phenotips.org/rel/owner"
}, {
"allowedMethods": ["DELETE", "GET", "PATCH", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/collaborators",
"rel": "https://phenotips.org/rel/collaborators"
}, {
"allowedMethods": ["GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/visibility",
"rel": "https://phenotips.org/rel/visibility"
}, {
"allowedMethods": ["DELETE", "GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008",
"rel": "https://phenotips.org/rel/patientRecord"
}],
"owner": {
"links": [{
"allowedMethods": ["GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/owner",
"rel": "https://phenotips.org/rel/owner"
}],
"id": "xwiki:XWiki.Mary",
"name": "Mary",
"type": "user"
},
"visibility": {
"links": [{
"allowedMethods": ["GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/visibility",
"rel": "https://phenotips.org/rel/visibility"
}],
"level": "public",
"label": "public",
"description": "All registered users can view public cases."
},
"collaborators": {
"links": [{
"allowedMethods": ["DELETE", "GET", "PATCH", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/collaborators",
"rel": "https://phenotips.org/rel/collaborators"
}],
"collaborators": [{
"links": [{
"allowedMethods": ["DELETE", "GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/collaborators/xwiki:XWiki.JohnDoe",
"rel": "https://phenotips.org/rel/collaborator"
}],
"id": "xwiki:XWiki.JohnDoe",
"name": "John Doe",
"email": "JohnDoe@Jupiter.com",
"type": "user",
"level": "edit"
}, {
"links": [{
"allowedMethods": ["DELETE", "GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/collaborators/xwiki:XWiki.Mary",
"rel": "https://phenotips.org/rel/collaborator"
}],
"id": "xwiki:XWiki.Mary",
"name": "Mary",
"type": "user",
"level": "owner"
}]
}
}

Update permissions using PUT

HTTP method: PUT
URL: http://localhost:8088/rest//patients/{id}/permissions

To replace the permissions for a patient record, identified by its internal PhenoTips identifier, from its JSON representation containing all the required fields as shown below.

{
 "owner": {"id": "xwiki:XWiki.JohnDoe"},
 "visibility": {"level": "public"},
 "collaborators": {"collaborators":[{"id":"xwiki:XWiki.PeterBrown","level":"view"},{"id":"xwiki:Groups.Arrhythmia research group","level":"edit"}]}
}

Example curl request:

curl -u Admin:admin -H "Content-Type:application/json" -X PUT
-d '{"owner":{"id":"xwiki:XWiki.JohnDoe"},
    "visibility":{"level":"public"},
    "collaborators":{"collaborators":[{"id":"xwiki:XWiki.PeterBrown", "level":"view"},{"id":"xwiki:Groups.Arrhythmia research group","level":"edit"}]}}'
http://localhost:8088/rest/patients/P0000008/permissions

Add/update collaborator using PATCH

HTTP method: PATCH
URL: http://localhost:8088/rest//patients/{id}/permissions

To add/update collaborator to/of the patient record with id P0000008 to be the user with username JohnDoe, we need to specify id and the collaborators id and access level. All other permission data will remain unchanged.

Example INPUT
A full reference is preferred, but just a username is also accepted.

{"collaborators" : [{"id":"xwiki:XWiki.Mary","level":"view"}]}

or

{"collaborators" : [{"id":"Mary","level":"view"}]}

Example curl request:

curl -H "Content-Type:application/json" -X PATCH -d '{"collaborators":[{"id":"xwiki:XWiki.Mary","level":"view"}]}' http://localhost:8088/rest/patients/P0000008/permissions/collaborators

Update owner using PATCH

HTTP method: PATCH
URL: http://localhost:8088/rest//patients/{id}/permissions

To change the owner of the patient record with id P0000008 to be the user with username JohnDoe, we need to specify id and the owner's key-value pair (below). All other permission data will remain unchanged.

{ "owner": { "id": "xwiki:XWiki.JohnDoe" }}

Example curl request:

curl -H "Content-Type: application/json" -X PATCH -d '{ "owner":{"id" : "xwiki:XWiki.JohnDoe"}}'  http://localhost:8088/rest/patients/P0000008/permissions

Retrieve owner

HTTP method: GET
URL: http://localhost:8088/rest//patients/{id}/permissions

For an existing patient record with an id value of P0000008, replace {id} in the url with P0000008.

Example curl request:

curl -H "Content-Type: application/json" -X GET http://localhost:8088/rest/patients/P0000008/permissions/owner

Example response body:


{
"links": [{
"allowedMethods": ["GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/owner",
"rel": "self"
}, {
"allowedMethods": ["GET", "PUT", "PATCH"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions",
"rel": "https://phenotips.org/rel/permissions"
}, {
"allowedMethods": ["DELETE", "GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008",
"rel": "https://phenotips.org/rel/patientRecord"
}],
"id": "xwiki:XWiki.JohnDoe",
"name": "John Doe",
"email": "JohnDoe@Jupiter.com",
"type": "user"
}

Update owner

HTTP method: PUT
URL: http://localhost:8088/rest//patients/{id}/permissions/owner

To change the owner of the patient record with id P0000008 to be the user with username/groupname xwiki:XWiki.Mary, we need to specify id and the owner username/groupname. All other permission data will remain unchanged.

Example curl request:

curl -H "Content-Type: application/json" -X PUT -d '{"id" : "xwiki:XWiki.Mary"}'  http://localhost:8088/rest/patients/P0000008/permissions/owner

Retrieve collaborators

HTTP method: GET
URL: http://localhost:8088/rest//patients/{id}/permissions/collaborators

For an existing patient record with an id value of P0000008, replace {id} in the url with P0000008.

Example curl request:

curl -H "Content-Type: application/json" -X GET http://localhost:8088/rest/patients/P0000008/permissions/collaborators

Example response body:


{
"links": [{
"allowedMethods": ["DELETE", "GET", "PATCH", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/collaborators",
"rel": "self"
}, {
"allowedMethods": ["GET", "PUT", "PATCH"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions",
"rel": "https://phenotips.org/rel/permissions"
}, {
"allowedMethods": ["DELETE", "GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008",
"rel": "https://phenotips.org/rel/patientRecord"
}],
"collaborators": [{
"links": [{
"allowedMethods": ["DELETE", "GET", "PUT"],
"href": "http://localhost:8088/rest/patients/P0000008/permissions/collaborators/xwiki:XWiki.JohnDoe",
"rel": "https://phenotips.org/rel/collaborator"
}],
"id": "xwiki:XWiki.JohnDoe",
"name": "John Doe",
"email": "JohnDoe@Jupiter.com",
"type": "user",
"level": "manage"
}]
}

Update all collaborators

HTTP method: PUT
URL: http://localhost:8088/rest//patients/{id}/permissions/collaborators

To add Mary whose user name is Mary with view rights and Peter whose user name is PeterBrown{ with edit rights as collaborators to the patient record, we need to specify patients record id, collaborators user names and their respective access levels (view, edit, manage). Collaborator(s) previously associated with the patient record will be replaced with the new ones.

Example curl request:

curl -H "Content-Type:application/json" -X PUT -d '{"collaborators":[{"id":"Mary","level":"view"},{"id":"PeterBrown","level":"edit"}]}' http://localhost:8088/rest/patients/P0000008/permissions/collaborators

Update specific collaborator

HTTP method: PATCH
URL: http://localhost:8088/rest//patients/{id}/permissions/collaborators

To add a new collaborator, or updates the permission level of an existing one use PATCH method, which unlike method PUT does not remove previously assigned collaborators.
For the patient record with id P0000008 to add/update collaborator whose username is JohnDoe, we need to specify id and the collaborator's username and access level values (below). 

{"collaborators":[{"id":"JohnDoe","level":"edit"}]}

]Example curl request:

curl -H "Content-Type:application/json" -X PATCH -d '{"collaborators":[{"id":"JohnDoe","level":"edit"}]}' http://localhost:8088/rest/patients/P0000008/permissions/collaborators

Delete all collaborators

HTTP method: DELETE
URL: http://localhost:8088/rest//patients/{id}/permissions/collaborators

Example curl request:

curl -X DELETE http://localhost:8088/rest/patients/P0000008/permissions/collaborators

Delete specific collaborator

HTTP method: DELETE
URL: http://localhost:8088/rest//patients/{id}/permissions/collaborators/{id}

Example curl request:

curl -X DELETE http://localhost:8088/rest/patients/P0000008/permissions/collaborators/JohnDoe