PhenoTips » Developer Guide » API » Families RESTful API

Families RESTful API

This page is a draft.

Starting with version 1.3 Milestone 6, PhenoTips provides a RESTful API for reading and modifying family data. The REST services allow to list existing families records, add a new family record, retrieve, modify or delete an existing family record with the given identifier. Data is exchanged in JSON format. The JSON representation of a patient record that is produced or that can be consumed by the PhenoTips RESTful API is specified in the Families JSON import/export section of the developer guide.

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.

Root resources

/families[?[start={integer}][&number={integer}][&orderField={...}][&order={...}]]

  • HTTP method: GET

    Media types
    application/json
    Result:
    Lists families visible by the requester.
    Family format: a JSON array of JSON objects, each object either a family JSON object or a custom summary which includes family ID, URL, modification date, etc.)
    :
    Parameters:
    start: for large result set paging, the index of the first patient to display in the returned page; defaults to 0
    number: for large result set paging, how many patients to display in the returned page; defaults to 30
    Status codes:
    200 if the request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 

/families

  • HTTP method: POST

    Accepted media type:
    application/json
    Media type:
    application/json
    Result:
    If successful, creates a new family record and returns its location, otherwise provides an error report
    Status codes:
    201 if the patient was created
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    500 if creating the patient failed

Family resources

/families/{id}

  • HTTP method: GET

    Media type:
    application/json
    Result:
    Retrieves a family record, identified by its internal PhenoTips identifier, in its JSON representation. If the indicated family record doesn't exist, or if the user sending the request doesn't have the right to view the target patient record, an error is returned.
    Status codes:
    200 if 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 type:
    application/json
    Result:
    Updates a family record, identified by its internal PhenoTips identifier, from its JSON representation. If the indicated family record doesn't exist, or if the user sending the request doesn't have the right to modify it, no change is performed and an error is returned. If a field is set in the patient record, but missing in the provided JSON, then that field is not changed.
    Status codes:
    202 if the patient was updated.
    304 if the patient was not modified.
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found
    NEWCODE if update failed because can't update only some of the patients in the family (e.g. family JSON implies linking new patients to family, and they can't be linked - possibly separate error codes for different reasons
  • HTTP Method: DELETE

    Media type:
    application/json
    Result:
    Deletes a family record

Patients resources

Reading the family should also be available through

/patients/{id}/family
  • HTTP method: GET

    Media type:
    application/json
    Result:
    Retrieves a family record, identified by its given identifier, in its JSON representation. If the indicated patient's family record doesn't exist, or if the user sending the request doesn't have the right to view the target patient record, an error is returned. 
    Status codes:
    200 if request was successful
    300 if multiple patient records with the same given identifier exist
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

Basic examples using a REST client

The examples use a root URI running a PhenoTips instance locally on port 8080:

http://localhost:8080/rest/patients
 

View all families

HTTP method: GET
URL: http://localhost:8080/rest/families

With a REST client browser extension, select the HTTP method and fill in the appropriate URL for the request. In this case, we would select GET and input the URL above. 

Example httpie request:

http --session=JohnDoe GET http://localhost:8080/rest/families

Example curl request:

curl http://localhost:8080/rest/families

Example response body:

{
"metadata": {
"returnedFamilies": 3,
"totalVisibleFamilies": 3,
"requestedPageSize": 30
},
"data": [{
"metadata": {
"createdBy": "XWiki.Admin",
"lastModifiedBy": "XWiki.Admin",
"version": "1.1",
"createdOn": "2016-12-20T14:07:20.000-05:00",
"lastModifiedOn": "2016-12-20T14:07:20.000-05:00"
},
"externalId": "",
"id": "FAM0000001"
}, {
"metadata": {
"createdBy": "XWiki.Admin",
"lastModifiedBy": "XWiki.Admin",
"version": "2.1",
"createdOn": "2016-12-21T12:59:12.000-05:00",
"lastModifiedOn": "2016-12-21T12:59:37.000-05:00"
},
"externalId": "ID-11111",
"id": "FAM0000002"
}, {
"metadata": {
"createdBy": "XWiki.Admin",
"lastModifiedBy": "XWiki.Admin",
"version": "2.1",
"createdOn": "2016-12-21T13:00:15.000-05:00",
"lastModifiedOn": "2016-12-21T13:02:12.000-05:00"
},
"externalId": "Green",
"id": "FAM0000003"
}]
}

View a single family record

HTTP method: GET
URL: http://localhost:8080/rest/families/{id}

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

Example httpie request:

http --session=JohnDoe GET http://localhost:8080/rest/families/FAM0000003

Example curl request:

curl http://localhost:8080/rest/families/FAM0000003

Example response body:

{
"externalId": "Green",
"warning": "",
"links": [{
"rel": "self",
"href": "http://localhost:8080/rest/families/FAM0000003",
"allowedMethods": ["DELETE", "GET"]
}],
"id": "FAM0000003",
"familyMembers": [{
"identifier": "MRN22222",
"reports": {},
"permissions": {
"hasView": true,
"hasEdit": true
},
"name": "Sonya Green",
"id": "P0000003",
"url": "http://localhost:8080/P0000003"
}, {
"identifier": "",
"reports": {},
"permissions": {
"hasView": true,
"hasEdit": true
},
"name": "Mother Yellow",
"id": "P0000005",
"url": "http://localhost:8080/P0000005"
}, {
"identifier": "",
"reports": {},
"permissions": {
"hasView": true,
"hasEdit": true
},
"name": "Father Blue",
"id": "P0000004",
"url": "http://localhost:8080/P0000004"
}]
}