API specification

The API allows third party software to interface with the Phenotype Database.

prerequisites

  • a valid username / password with role ROLE_CLIENT (log in to see if you have this role assigned to your account), see authenticate for usage.
  • an api key (used to calculate the validation md5 hash, log in to get your api key. )
  • a deviceID / clientID (look here for an iOS library or here for how the PHP client calculates it). The concept of the deviceID is easier to understand when thinking about -for example- iPhones. Every iPhone has a UDID (unique device identifier) which is a sequence of 40 letters and numbers that is specific to your device, so no other device has the same UDID. The concept of the deviceID in this API is similar, however in the case of the this api it is more likely that a number of users will use the api on the same device. In order to properly generate a unique identifier you would probably need a hardware identifier plus a user identifier. At the moment we advise to create an md5sum of the concatenation of a stable unique hardware identifier (like the MAC Address of your first network card) and a dynamic user name or id, e.g. md5sum( MAC-address + script path + user name/id ). See the examples for more information...
  • available API calls

  • authenticate - set up / synchronize client-server session
  • getStudies - fetch all (readable) studies
  • getSubjectsForStudy - fetch all subjects in a given study
  • getSubjectGroupsForStudy - fetch all subjectGroups in a given study
  • getSampleAndTreatmentGroupsForStudy - fetch all sample & treatment groups in a given study
  • getTreatmentTypesForStudy - fetch all treatment types in a given study
  • getSampleTypesForStudy - fetch all subjectGroups in a given study
  • getAssaysForStudy - fetch all assays in a given study
  • getSubjectsForAssay - fetch all subjects in a given assay
  • getSamplesForAssay - fetch all samples in a given assay
  • getFeaturesAssay - fetch all features for a given assay
  • getMeasurementDataAssay - fetch all measurements for a given assay
  • SDK packages

  • R - R Client to interface with GSCF using R
  • PHP - Object Oriented SDK for interacting with GSCF using PHP (needs to be updated)
  • Groovy - Object Oriented SDK for interacting with GSCF using Groovy (needs to be updated)
  • authenticate

    url: https://dashin.eu/interventionstudies-test/api/authenticate

    Authenticate a client using HTTP BASIC authentication. This API call is used to:

  • initially set up a client/server session
  • re-synchronise client/server sessions that become out of sync (e.g. sequence differences)
  • After successful authentication, a session token is returned which should the client should store locally. This session token should be used in all subsequent calls to calculate the validation md5 hash.

    This call should also be performed whenever a client/server sessions becomes out of sync (e.g. the client's sequence count differs from the server's sequence count) as the server's sequence count will be returned after successfully authenticating. For security reasons this api method is designed to be called only once (or when sessions are out of sync) as HTTP BASIC authentication is not really secure (if someone is able to sniff your traffic, the authentication md5 hash is easily stolen). API calls are validated using the calculated md5 hash.

    Every subsequent request the client does, needs to contain the validation MD5 hash, which is a MD5 sum of the concatenation of the device token, the request sequence and the api key (e.g. md5sum( token + sequence + api key ) ).
    Note that in order to be able to successfully authenticate or use the API in general, the user should have the ROLE_CLIENT assigned!

    Request parameters

    argument type length description example required
    deviceID string 32 a unique stable ID of the client device / application performing the call (iOS example, PHP example, for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes

    Reply parameters

    argument type length description example
    token string 36 a unique token for setting up a client session 9ae87836-d38d-4b86-be6a-eff93f2b049a
    sequence int - the api call count for this session 231

    example reply

    { "token":"78b070a6-e68c-436e-a81b-2db08840e809", "sequence":0 }

    getStudies

    url: https://dashin.eu/interventionstudies-test/api/getStudies

    Returns the studies which are readable and/or writable for the client. If the client should get access to a particular study, the client's username (used to authenticate) should be added as a reader to the study.

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes

    example reply

    { "count":2, "studies": [ { "token":"f2e085fb-9138-4ebe-a59f-82f1bdc21d7e", "title":"NuGO PPS human study", "code":"NuGO_PPSH", "description":"Human study performed at RRI; centres involved: RRI, IFR, TUM, Maastricht U.", "subjectCount":11, "species":["Homo sapiens"], "assays":["Mass Sequencing module","SAM module for clinical data","Metabolomics module"], }, { "token":"6b7e85b3-b174-492c-ba27-fbfb71ab9b8b", "title":"NuGO PPS3 mouse study leptin module", "code":"NuGO_PPS3", "description":"C57Bl/6 mice were fed a high fat (45 en%) or low fat (10 en%) diet after a four week run-in on low fat diet.", "subjectCount":80, "species":["Mus musculus"], "assays":["SAM module for clinical data","Metabolomics module"], } ] }

    getSubjectsForStudy

    url: https://dashin.eu/interventionstudies-test/api/getSubjectsForStudy

    Returns the subjects for a particular study

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    studyToken string 255 study token (see getStudies) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":11, "subjects": [ { "id":81, "name":"1", "species":"Homo sapiens", "Gender":"Female", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":82, "name":"2", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":83, "name":"3", "species":"Homo sapiens", "Gender":"Female", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":84, "name":"4", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":85, "name":"5", "species":"Homo sapiens", "Gender":"Female", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":86, "name":"6", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":87, "name":"7", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":88, "name":"8", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":89, "name":"9", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":90, "name":"10", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":91, "name":"11", "species":"Homo sapiens", "Gender":"Female", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null } ] }

    getSubjectGroupsForStudy

    url: https://dashin.eu/interventionstudies-test/api/getSubjectGroupsForStudy

    Returns the subjectGroups for a particular study

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    studyToken string 255 study token (see getStudies) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":2, "subjectGroups":[] }

    getSampleAndTreatmentGroupsForStudy

    url: https://dashin.eu/interventionstudies-test/api/getSampleAndTreatmentGroupsForStudy

    Returns the sample & treatment groups for a particular study

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    studyToken string 255 study token (see getStudies) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":4, "sampleAndTreatmentGroups":[] }

    getTreatmentTypesForStudy

    url: https://dashin.eu/interventionstudies-test/api/getTreatmentTypesForStudy

    Returns the treatment types for a particular study

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    studyToken string 255 study token (see getStudies) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":1, "treatmentTypes":[] }

    getSampleTypesForStudy

    url: https://dashin.eu/interventionstudies-test/api/getSampleTypesForStudy

    Returns the sample types for a particular study

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    studyToken string 255 study token (see getStudies) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":4, "sampleTypes":[] }

    getAssaysForStudy

    url: https://dashin.eu/interventionstudies-test/api/getAssaysForStudy

    Returns the assays for a particular study

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    studyToken string 255 study token (see getStudies) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":6, "assays": [ { "token":"253ec24f-9bac-4f2b-b9cf-f84b86376a4e", "name":"16S Sequencing assay", "module":"Mass Sequencing module", "Description":null }, { "token":"4df2f49d-1d8c-48bd-8ebd-d267164948ec", "name":"18S Sequencing assay", "module":"Mass Sequencing module", "Description":null }, { "token":"828cf2d6-d797-484b-82f9-df9933d76d77", "name":"Glucose assay after", "module":"SAM module for clinical data", "Description":null }, { "token":"d68e8fed-41ca-4408-9d8e-f3598eca9183", "name":"Glucose assay before", "module":"SAM module for clinical data", "Description":null }, { "token":"32945764-6c5e-497c-8b1e-0d5e0dfa8221", "name":"Lipidomics profile after", "module":"Metabolomics module", "Description":null, "Spectrometry technique":"GC/MS" }, { "token":"92f42f77-1c13-4b25-aa57-b444e355fbf4", "name":"Lipidomics profile before", "module":"Metabolomics module", "Description":null, "Spectrometry technique":"GC/MS" } ] }

    getSubjectsForAssay

    url: https://dashin.eu/interventionstudies-test/api/getSubjectsForStudy

    Returns the subjects for a particular assay. Not all study subjects have to be in an assay.

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    assayToken string 255 assay token (see getAssays) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":4, "subjects": [ { "id":81, "name":"1", "species":"Homo sapiens", "Gender":"Female", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":82, "name":"2", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":83, "name":"3", "species":"Homo sapiens", "Gender":"Female", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null }, { "id":84, "name":"4", "species":"Homo sapiens", "Gender":"Male", "Age":null, "DOB":null, "Height":null, "Weight":null, "BMI":null, "Race":null, "Waist circumference":null, "Hip circumference":null, "Systolic blood pressure":null, "Diastolic blood pressure":null, "Heart rate":null, "Run-in-food":null } ] }

    getSamplesForAssay

    url: https://dashin.eu/interventionstudies-test/api/getSamplesForAssay

    Returns the samples data for a particular assay

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    assayToken string 255 assay token (see getAssays) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":11, "samples": [ { "Remarks":null, "Sample measured volume":null, "Text on vial":"T58.66620961739546", "material":"blood plasma", "name":"7_A", "token":"c705668a-81c4-4d80-83df-96bb477aeb0b" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T39.7483280873287", "material":"blood plasma", "name":"9_A", "token":"d81bdda8-4684-45b9-b254-1ec4756cfc71" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T43.20628871191769", "material":"blood plasma", "name":"2_A", "token":"2f501b55-ffdd-4bf2-a598-dcf24d3fac63" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T88.40760089710538", "material":"blood plasma", "name":"8_A", "token":"f908ae2a-3df7-4eb7-be2a-0b8859c20bfc" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T58.14619508995611", "material":"blood plasma", "name":"11_A", "token":"6763cff4-8113-4614-85b9-ef98fb34beba" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T71.86067212685215", "material":"blood plasma", "name":"6_A", "token":"5a339aaa-9bb6-4a0a-9ce7-4c42ceaf5771" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T2.395117860298579", "material":"blood plasma", "name":"3_A", "token":"a9e73abe-aed3-4c43-8fe7-a6b3dfe6e2ed" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T98.99437236833568", "material":"blood plasma", "name":"10_A", "token":"3e63a493-c69d-4cd4-ba23-eeafe962b17f" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T25.420102086098005", "material":"blood plasma", "name":"4_A", "token":"34d5611b-7407-489a-b25a-00ad2b0d8789" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T69.55369597806298", "material":"blood plasma", "name":"1_A", "token":"5c9dce07-ca4d-4bcb-8ac3-c8488bd7247a" }, { "Remarks":null, "Sample measured volume":null, "Text on vial":"T50.41146383561054", "material":"blood plasma", "name":"5_A", "token":"21a07d33-6d95-46f9-a80d-cd58d7e140d0" } ] }

    getFeaturesForAssay

    url: https://dashin.eu/interventionstudies-test/api/getFeaturesForAssay

    Returns the features for a particular assay

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    assayToken string 255 assay token (see getAssays) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":100, "features":[] }

    getMeasurementDataForAssay

    url: https://dashin.eu/interventionstudies-test/api/getMeasurementDataForAssay

    Returns the measurement data for a particular assay

    Request parameters

    argument type length description example required
    deviceID string 36 (max) a unique stable identifier of the device making the call (for example: md5sum(mac-address+username)) 9ae87836-d38d-4b86-be6a-eff93f2b049a yes
    validation string - md5sum( token + sequence + api key ) 9ae87836d38d4b86be6aeff93f2b049a yes
    assayToken string 255 assay token (see getAssays) b6e0c6f4-d8db-4a43-91fa-a157d2d492f0 yes

    example reply

    { "count":500, "measurements":[] }