PhenoTips » Developer Guide » API » Consents RESTful API

Consents RESTful API

Starting with version 1.3 Milestone 1 PhenoTips provides a RESTful API ability to list and manipulate consents associated with a patient record.

A consent is described by the following:

  • id: An internal, short identifier for the consent.
  • label: The human readable text of the consent.
  • isRequired: Possible values: true or false. If a consent is required, then no patient data is visible unless the consent is granted.
  • formFields: Optional list of patient data fields which will be hidden if this consent is not granted.
  • status: Possible values: "yes" or "no". The current status of the consent for the given patient.

The REST services allow listing the available consents and their status for a specific patient, as well as granting, revoking, and bulk-assigning consent statuses for a patient.

Resources

Resource URIs are specified using URI templates. Bracketed elements are formal parameters and should be instantiated to actual values in order to retrieve the associated resource.

List consents

/patients/{id}/consents

  • HTTP Method: GET

    Media type:
    application/json
    Result:
    Retrieves a list of all consents for a given patient. Example output:
    [{
    "id": "real",
    "label": "I confirm that the data entered in this form corresponds to a real patient.",
    "isRequired": true,
    "status": "yes"
    }, {
    "id": "genetic",
    "label": "I confirm that consent has been obtained to share this patient's genetic sequencing data (e.g., a VCF file) on restricted access databases.",
    "isRequired": false,
    "formFields": ["org.phenotips.patientSheet.field.vcf", "org.phenotips.patientSheet.field.variantdisplay"],
    "status": "no"
    }, {
    "id": "share_images",
    "label": "I confirm that consent has been obtained to share this patient's medical images/photos on restricted access databases.",
    "isRequired": false,
    "status": "yes"
    }]
    Status codes:
    200 if request was successful
    403 if the user does not have the right to access the patient
    404 if the specified patient does not exist
    Example curl request:
    curl -u Admin:admin http://localhost:8080/rest/patients/P0000001/consents

Mark a consent as granted

  • HTTP Method: PUT

    Accepted media type:
    text/plain
    Expected input:
    the identifier of the consent to be granted
    Result:
    Marks a specific consent as granted for a given patient. No response body will be generated.
    Status codes:
    200 if request was successful
    400 if the specified consent is not valid
    403 if the user does not have the right to access the patient or modify consents
    404 if the specified patient does not exist
    Example curl request:
    curl -u Admin:admin -H "Content-Type: text/plain" -X PUT -d 'real' http://localhost:8080/rest/patients/P0000001/consents/grant

Mark a consent as not granted

  • HTTP Method: PUT

    Accepted media type:
    text/plain
    Expected input:
    the identifier of the consent to be revoked
    Result:
    Marks a specific consent as not granted for a given patient. No response body will be generated.
    Status codes:
    200 if request was successful
    400 if the specified consent is not valid
    403 if the user does not have the right to access the patient or modify consents
    404 if the specified patient does not exist
    Example curl request:
    curl -u Admin:admin -H "Content-Type: text/plain" -X PUT -d 'genetic' http://localhost:8080/rest/patients/P0000001/consents/revoke

Specify which consents are granted

/patients/{id}/consents/assign

  • HTTP Method: PUT

    Accepted media type:
    application/json
    Expected input:
    A JSON array listing the identifiers of the consents to be granted.
    Result:
    Marks the specified consents as granted for a given patient. Any consent not present in this list will be revoked, if previously granted. No response body will be generated.
    Status codes:
    200 if request was successful
    400 if any of the specified consents is not valid
    403 if the user does not have the right to access the patient or modify consents
    404 if the specified patient does not exist
    Example curl request:
    curl -u Admin:admin -H "Content-Type: application/json" -X PUT -d '["real", "genetic"]' http://localhost:8080/rest/patients/P0000001/consents/assign