Examples¶
Attention
All NHS Genomic Medicine Service referral and variant/interpretation data will only be available on the api/2 endpoints.
As of December 4th, 2017, CIPAPI V1 will be supported for any bug fixes, but all updates and swagger UI documentation will support V2 of the CIPAPI. Both V1 and V2 webservices endpoints are available.
If you are using CIPAPI V1 endpoints, please check the endpoints at API List of Endpoints. Certain V1 endpoints require /api/1/ and others require /api/. This has been standardised for all CIPAPI V2 endpoints, which are prefixed by /api/2/.
For all usage queries shown below, python v2.7 will be used for demonstrative purposes. To maintain consistency, all code blocks will be showing API V1
Example: List of Interpretation Requests Endpoint¶
- URL V2: /api/2/interpretation-request
- Method: GET
- Content Type: “application/json”
Attention
A new parameter has been added to this end point to filter by referral by it's category.
Called category, the accepted values are gms, 100k, experimental and other.
If your were using this end point to get a list of only 100k Interpretation Requests you should start using this parameter as in: ?category=100k
Do note that if a user does NOT use the category parameter, all cases (100k, gms, experimental, and other) that the user is authorised to see will by default be returned.
The result of this endpoint is to present to the user a paginated overview of the list of referrals they are allowed to inspect.
Use format to construct the full URL.
Pass this URL to the get_url_json_response function to retrieve a json that has all of the associated Interpretation Requests that your credentials will allow you to view, in a paginated format.
Inspect the results
>>> type(IR_list)
dict
>>>IR_list.keys()
[u'count', u'previous', u'results', u'next']
>>>type(IR_list['results'])
list
>>>len(IR_list['results'])
100
>>>IR_list = get_url_json_response(url=IR_list_url+'?page=11')
>>>ir_id, ir_version = map(str, IR_list['results'][0]['interpretation_request_id'].split('-'))
>>>ir_id, ir_version
('1011', '1')
Example: Specific Interpretation Request Endpoint¶
- URL V2: /api/2/interpretation-request/{ir_id}/{ir_version}
- Method: GET
- Content Type: “application/json”
interpretation_request_data¶
This endpoint is used to retrieve all the information available about a specific referral.
The data that is returned will be a combination of CIP-API database administrative information and the
InterpretationRequest, any InterpretedGenomes, and ClinicalReports and the ExitQuestionnaire associated to
this case, these ones are defined following models in GelReportModels.
More information on GeLReportModels can be found in the background section here: Background: GeLReportModels
And examples of the data returned can be found here
IR_case_url = CIP_API_SERVER_URL.format(endpoint='interpretation-request/{ir_id}/{ir_version}/')
IR_case_url = IR_case_url.format(ir_id=ir_id, ir_version=ir_version)
case_data = get_url_json_response(url=IR_case_url)
>>>case_data.keys()
[u'status', u'files', u'case_priority', u'labkey_links', u'number_of_samples', u'proband', u'tags', u'gel_tiering_qc_outcome', u'created_at', u'interpretation_request_id', u'sample_type', u'cohort_id', u'version', u'family_id', u'last_status', u'interpretation_request_data', u'assembly', u'interpreted_genome', u'cip', u'clinical_report']
>>>type(case_data['interpretation_request_data'])
dict
>>>case_data['intereptation_request_data'].keys()
[u'json_request']
>>>type(case_data['interpretation_request_data']['json_request'])
dict
>>>case_data['interpretation_request_data']['json_request'].keys()
[u'genomeAssemblyVersion', u'virtualPanel', u'pedigreeDiagram', u'analysisVersion', u'TieringVersion', u'additionalInfo', u'analysisReturnURI', u'pedigree', u'genePanelsCoverage', u'InterpretationRequestID', u'BAMs', u'annotationFile', u'VCFs', u'InterpretationRequestVersion', u'TieredVariants', u'interpretGenome', u'bigWigs', u'modeOfInheritance', u'versionControl', u'workspace', u'otherFamilyHistory', u'complexGeneticPhenomena', u'cellbaseVersion']
To retrieve the interpretation_request_data isolated from the case_data metadata and the interpreted_genome list and clinical_report list, perform the following:
Example data retrieved from interpretation_request_data:
Attention
The interpretation_request_data is type dict whereas interpreted_genome and clinical_report are type list,
as there will always be one unique interpretation_request_data for a case, which will have appended to it a set
of one to many interpreted_genomes and clinical_reports, due to either multiple third party interpretation
providers or versions of generated reports from an MDT tool, respectively.
If GeL runs the GeL interpretation pipeline again for the same case, a new ir_version is created which has a new,
singular interpretation_request_data and any interpreted_genomes and/or clinical_reports will be based off
of this new version independent of any previous version(s). This new case version can be accessed by incrementing
the ir_version in the CIP-API InterpretationRequests webservices endpoint.
Using "extra-params="¶
Both the "/api/2/interpretation-request" list and "/api/2/interpretation-request/{ir_id}/{ir_version}" endpoints can be used with the "extra-params=" parameter to return additional information not returned by default.
The list of available extra parameters are detailed below:
| parameter | Description |
|---|---|
| long_names | 100K only - returns the full name of the 100K GMC |
| show_referral | GMS only - returns the referral & referral test object in the response |
| show_interpretation_flags | Adds Interpretation Flags associated with each case if present |
| dss_arrival_date | Returns the date the referral first loaded into the Decision Support System (DSS) |
Attention
Multiple extra params can be supplied at the same time e.g. &extra_params=show_referral,dss_arrival_date would return
both the referral information & the DSS arrival date
interpreted_genome¶
As there can be many Interpreted Genome entries appended to the case, organised as list entries in the parent list
interpreted_genome, it is imperative to retrieve the latest one relevant to the case.
To clarify, an interpreted_genome = {interpreted_genome1, interpreted_genome2, ...}
The cip_version is the specific version of an interpreted_genome list entry. The latest cip_version that has API
state qc_passed and then has been moved to the API state sent_to_gmcs (see GeL Data Flow)
is what is provided in the TPI for review.
The latest interpreted_genome list entry is usually at index = 0 in the interpreted_genome list.
More information on GeLReportModels for the 'interpreted_genome' can be found in the background section here: Background: Interpreted Genome
And examples of the data returned can be found here
>>>interpreted_genome_list = case_data['interpreted_genome']
>>>print type(interpreted_genome_list)
list
>>>interpreted_genome = case_data['interpreted_genome'][0]
>>>print type(interpreted_genome)
dict
>>>interpreted_genome.keys()
[u'interpreted_genome_data', u'status', u'created_at', u'gel_qc_outcome', u'cip_version']
Attention
In the near future (not in scope with v3.0.0 or v4.0.0 of GeLReportModels) the Interpreted Genome list will be redefined to support multiple Interpreted Genomes from different interpretation services simultaneously for a case. Currently only one provider is allowed to produce an Interpreted Genome for a case.
clinical_report¶
The clinical_report list can have many clinical_report entries appended to the case.
It is imperative to retrieve the latest one relevant to the case.
To clarify, a clinical_report list = {clinical_report1, clinical_report2, ...}
The clinical_report_version is the specific version of an clinical_report list entry.
The latest clinical_report_version is the latest version of the primary findings entered by the GMC user in either
the DSS or the GeL Interpretation Browser for that case. This list entry is at index = -1 (latest entry) in the clinical_report list.
More information on GeLReportModels for the clinical_report can be found in the background section here: Background: Interpreted Genome
And examples of the data returned can be found here
>>>clinical_report_list = case_data['clinical_report']
>>>print type(clinical_report_list)
list
>>>clinical_report = case_data['clinical_report'][-1]
>>>print type(clinical_report)
dict
>>>clinical_report.keys()
[u'created_at', u'clinical_report_data', u'exit_questionnaire', u'clinical_report_version', u'valid']
exit_questionnaire¶
An exit_questionnaire is associated to each clinical_report entry. It includes variant and case level questions
completed by Clinical Scientists in the GLHs when interpreting a referral
The clinical_report_version is the specific version of an clinical_report list entry.
The latest clinical_report_version is the latest version from variant and case data entered by the GMC user in either
the DSS or the GeL Tiering Browser for that case. This list entry is usually at index = -1 (latest entry) in the clinical_report list.
More information on GeLReportModels for the exit_questionnaire can be found in the background section here: Background: Interpreted Genome
Referral¶
Referral end points will be used to create and get a GMS referral. A referral will be associated to one or more Referral Tests. The CIP-API will create a Interpretation Request for each of the referral tests that are Whole Genome Sequencing, The link to the interpretation request information will be present in the response of these endpoints.
List Referral end point¶
- URL V2:/api/2/referral/
- Method:GET
- Content Type: “application/json”
Note
The full list of parameters can be found in the swagger documentation of this API.
Detail Referral end point¶
- URL V2:/api/2/referral/{referral_id}/
- Method:GET
- Content Type: “application/json”
These 2 end points share the same model for the referral object:
{
"referral_id": "string",
"referral_uid": "string",
"ordering_date": "2019-06-14",
"analysis_scope": "string",
"referral_data": "Dictionary following Referral Definition by GelReportModels",
"cohort_id": "string",
"group_id": "string",
"proband": "string",
"sample_type": "string",
"assembly": "string",
"last_modified": "2019-06-14T14:45:19.947Z",
"create_at": "2019-06-14T14:45:19.947Z",
"referral_test": [
{
"referral_test_id": "string",
"clinical_indication_test_type_id": "string",
"clinical_indication_test_code": "string",
"clinical_indication_test_name": "string",
"test_technology_id": "string",
"testTechnologyDescription": "string",
"ordering_date": "2019-06-14",
"interpretation_request": "Link to interpretation Request associated to this referral test",
"create_at": "2019-06-14T14:45:19.947Z",
"last_modified": "2019-06-14T14:45:19.947Z",
"interpreter_organisation_id": "string",
"interpreter_organisation_code": "string",
"interpreter_organisation_name": "string",
"interpreter_organisation_national_grouping_id": "string",
"interpreter_organisation_national_grouping_name": "string",
"interpretation_request_id": "string",
"interpretation_request_version": "string"
}
],
"requester_organisation_id": "string",
"requester_organisation_code": "string",
"requester_organisation_name": "string",
"requester_organisation_national_grouping_id": "string",
"requester_organisation_national_grouping_name": "string"
}
As part of this response the link to the interpretation request is provided. Please note that the interpretation request will be linked to a referral test and not to a referral.
Example: From Referral to Interpretation Request and from Interpretation Request to Referral¶
If you are working with either referrals or interpretation requests it is simple to go from one to the other using this API.
If you are using the Interpretation Request end points (detail or list) and you want to access referral information
this can be done using a query parameter called extra-params, this can take a comma separate list of values. If you add the parameter extra-params=show_referral, then a new section will appear in the response with the referral and referral test information, following the same schema documented previously in this section. This is shown in the next example.
In the next example we will go in the opposite direction from referral to interpretation request in this case is a bit more complex and an extra request is needed. As specified before the url to call from where the interpretation request will retrieve is part of the Referral end point, taking this in consideration here is how to do it:
referral_url = CIP_API_SERVER_URL.format(endpoint='referral/{referral_id}')
ir_case_url = referral_url.format(referral_id=referral_id)
referral_data = get_url_json_response(url=ir_case_url)
for referral_test in referral_data['referral_test']:
case_data = get_url_json_response(url=referral_test['interpretation_request'])
Notice here that one referral could have more than one referral test with an interpretation request, this won't be the usual, but still this consideration should be taken, as shown in the previous example.
Building objects from GeLReportModels¶
Further information on how to build python or java objects from the GelReportModels avro schema is documented here: http://gelreportmodels.genomicsengland.co.uk/
You can use the objects built from the avro schema to perform schema validation, iterative queries, schema migrations, and mock data.
An interactive tutorial using GeLReportModels is found here: https://github.com/genomicsengland/ACGS_GeL_API_workshop
For a GMS specific tutorial, please go here: https://github.com/genomicsengland/ACGS_GeL_API_workshop/tree/master/gms_integration
Using the Re-identification Service with the CIP-API¶
Like the data for the 100K project, the GMS referral data in CIP-API does not contain any Patient Identifiable Data (PID) i.e. names, DOBs, NHS numbers etc. However, whilst on the Health and Social Care Network (HSCN) the TOMS webservices can be used to make RESTful queries to specific TOMS environments to retrieve PID for GMS referrals from the "re-identification service".
This is the same process the GMS Interpretation Portal uses to add PID to its interface
You can retrieve PID from a particular environment’s re-identification service for any referrals generated in that TOMS environment.
Refer the Environment Access Guide for details of the different TOMS environment URLs.
TOMS beta and UAT instances do not use real patient data; however, you can use them to retrieve mock PID. Only the TOMs production service will contain PID.
Location of the endpoints¶
- Production host: https://api.genomics.nhs.uk
- UAT host: https://api.uat.genomics.nhs.uk
The endpoint format: https://{host}/reidentification/ is the root address for each TOMS
environment, where
For example, for the TOMs UAT environment, the following endpoints are available:
- https://api.uat.genomics.nhs.uk/reidentification/referral-pid-userauth
- https://api.uat.genomics.nhs.uk/reidentification/patient-pid-userauth
Retrieving PID with the NGIS GUID for a referral¶
- Query URL: https://api.uat.genomics.nhs.uk/reidentification/referral-pid-userauth
- Required Input: referral_id – GUID that identifies a referral in NGIS
-
Output: PID for the patient and all participants on the referral
-
Example referral-pid/{referral_id} query:
Request:
curl -X GET --header "Content-Type: application/json" --header "Authorization: Bearer
{JWT}" https://api.uat.genomics.nhs.uk/reidentification/referral-pid-userauth/<REFERRAL_ID>
Response:
{
"participants": [
{
"patient_id": "9e6560fe-d9e8-a-8a39-ab50a7f092a4",
"human_readable_id": "p75786904064",
"name": "Ms CORA CROOKS",
"date_of_birth": "2011-06-09",
"nhs_number": "9449306265"
}
],
"referral_id": "cfdd0422-79c7-4716-8178-48e56710691f",
"referral_human_id": "r19865100258"
}
Retrieving PID with the NGIS GUID for a patient¶
-
Note: to query this URL, you must have a patient_id value. This endpoint will return only the specific patients’ PID.
-
Required Input: patient_id – GUID that identifies a patient in NGIS
- Output: PID for the patient only
- Example patient-pid/{patient_id} query:
Request:
curl -X GET --header "Content-Type: application/json" --header "Authorization: Bearer
{JWT}" https://api.uat.genomics.nhs.uk/reidentification/patient-pid-userauth/<PATIENT_ID>
Response:
{
"ngis_uid": "9e6560fe-d9e8-a-8a39-ab50a7f092a4",
"human_readable_id": "p987654321",
"name": "Ms Gene HELIX",
"date_of_birth": "2000-01-01",
"nhs_number": "1234567890"
}
API List of Endpoints¶
The Swagger User Interface of the CIP-API has documentation of all endpoints and their respective query parameters and return payloads. However, this user interface only supports V2 of the API. You can see this information here: https://cipapi.genomicsengland.nhs.uk/api/2/docs/. All V2 endpoints that are backwards compatible with V1 endpoints share the same parameters.