PhenoTips » Design proposals » REST_Family

REST_Family

 To be updated by @asm

API use cases:
 1) families UI (replace current velocity with JS + AJAX)
 2) pedigree editor UI (replace custom endpoints with REST calls)
 3) front page widget, replicating full functionality of the current one
 4) (related) "browse all data" widget
 5) data manipulation by (authorized) 3rd parties/3-rd party software: view/retrieve, edit

Open questions:

 1) should list of families include full family JSONs or a custom summary, like it is currently done for rest/patients (related: remove XML option for rest/patients, and refactor to use the same structure we decide for families?)
    Full JSON:
    [+] easier to implement
    [+] full data available to UI or one call to retrieve multiple families for some software
    [-] perfromance in UI? (JAVA toJSON() called multiple times as opposed to one DB query)
    [+] performance for data retrieval, one call instead of 100 individual family calls
        (pedigree needed a similar functionality for patients to get all patients in one call + easier client-side code in pedigree)

 2) Should rest/families include more sorting options?
    [+] likely needed for live-table replacement widgets if paging is used (not needed if paging is done on the front-end)
    [-] too complicated/more work

 3) Family JSON - see below

 4) Error codes for updating families - more things may fail then when updating single patient

Family JSON

{
  same as patient JSON: 

  "id": "P00xxxx",
  "external_id": "...",
  "reporter": ...
  "meta": ...
  "contact": ...

  "members": [ "P0000xxx", "P0000yyyy", .... ],                 array of PhenoTips patient IDs 

  "pedigree": { ...pedigree JSON...},
  "notes": ...
}

Alternative: unlike patients, current user may not have edit/view rights for all the members in the family (not sure if view can happen, but definitely edit). Pedigree needs this information, and others might as well, so maybe use something similar to what pedigree gets:

"members": [ {"id":"P0000060", "name":"Merry Jenkins", "permissions": {"hasEdit":true,"hasView":true}, "identifier":"","url":"/P0000060"},
             {"id":"P0000059", "name":"Burt Jenkins", "permissions": {"hasEdit":false,"hasView":true}, "identifier":"ID001","url":"/P0000059"} ]

[+] one call => all information
[-] duplicating info

Or without duplication:

"members": [ {"id":"P0000060", "permissions":{"hasEdit":true,"hasView":true} },
             {"id":"P0000059", "permissions":{"hasEdit":false,"hasView":true} } ]

Also: information duplication between pedigree (which has all the members in one way or another) and separate list of members.
Separate list and separate pedigree JSON:
[+] MUCH more convenient, no need to parse (complicated) pedigree JSON
[-] information duplication in a way

REST 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

Availability

PhenoTips® is freely available under the terms of the the GNU Affero General Public License, version 3.0.

 Download the latest release
 Play with our demo
 Get the source code

Contact

 Ask for free support (by volunteers):
support@phenotips.org
 Inquire about commercial support:
info@gene42.com
 Follow us on twitter:
@phenotips

PhenoTips® is an exclusive trademark of Gene42 Inc.