Usage

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

NEW! Authentication (Webservices Access)

Client Credentials Flow Authentication with AD

Background

As part of NGIS implementation Genomics England is abandoning LDAP and adopting Active Directory (AD). This means that the authentication in the CIP-API will be delegated to AD. This will impact the  way systems such as internal pipelines, interpretation services (external and internal) and decision support systems authenticate against the CIP-API. 

A system, such as a GeL2MDT, will have one client_id, and one client_secret for a specific AD tenant. The token retrieved from the AD can be universally used for the following applications:

• GMS CIP-API
• GMS OpenCGA
• GMS Sample Matching Service (SNP Service)

Each application will authorise uniquely, but will accept the JWT token as a Bearer token in the header of any request. The systems do not need to login to any of these applications specifically. Instead, the systems need to authenticate to the AD tenant, retrieve the token, and then query directly to any desired endpoint in these applications with the token in the header of the request.

---

Authentication Method

The authentication method will be the same we are using at the moment, based on a Bearer Token present in the header of each request. This token will have an expiration time, clients should get a new one when this happens. The Authentication flow we will be using is called OAuth 2.0 Client Credentials Grant Flow. You can review this in the official documentation

The OAuth 2.0 Client Credentials Grant Flow permits a web service (confidential client) to use its own credentials instead of impersonating a user, to authenticate when calling another web service. In this scenario, the client is typically a middle-tier web service, a daemon service, or web site. For a higher level of assurance, Azure AD also allows the calling service to use a certificate (instead of a shared secret) as a credential.

1. The client application authenticates to the Azure AD token issuance endpoint and requests an access token.
2. The Azure AD token issuance endpoint issues the access token.
3. The access token is used to authenticate to the secured resource.
4. Data from the secured resource is returned to the client application.

In the example above, the client application is e.g. a GeL2MDT application; and the Resource Web API is the CIP-API.

---

Obtaining the token

To obtain the token the clients will need to be registered as applications in AD. This will be managed by Genomics England (service desk). Clients need both a client_id (appid) and a client_secret, both of them will be long-lasting, clients won't need to update them unless Genomics England consider they are compromised or they are about to expire - in this case Genomics England will ensure this is communicated within a reasonable window -. The method to get the token is described in this link and a working example in different programmting languages, can be found below:

The following examples have been created using Genomics England non prod AD tenant (afee026d-8f37-400e-8869-72d9124873e4) see Azure AD Non Production Host, once the production environment is configured, the tenant id and the secrets will be shared with the clients.

If you need a client_id and client_secret, please contact GeL Service desk: ge-servicedesk@genomicsengland.co.uk and in your request ask for a client_id and client_secret for CIP-API GMS interoperabliity testing.

Curl

curl -X POST \
  https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/token \
  -H 'Accept: application/json' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Authorization: Basic OWQ0ODYzYjEtYmU4ZC00ZTMyLWFmOTktNDM1NWVasdsadZUWVBPdWJQdUliUUYyTUJFL1VrSHVEdzNuUWZvSGlWdTNPVlJ6TkdrZWM9' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: multipart/form-data; boundary=--------------------------052831142206095611213706' \
  -H 'Host: login.microsoftonline.com' \
  -F grant_type=client_credentials

This python example passes the client_id and client_secret as base64 encoded as a "Authorisation: Basic " header.

Python

import requests


client_id = "49394eae-7f7d-4882-b932-8asdsad0d3aa9"
client_secret = "NkS1hEjGdpelUax119RHyQPIasdsadd89cx+2rsUSk="
url = "https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/token"

payload = "grant_type=client_credentials"
headers = {
    'Content-Type': "application/x-www-form-urlencoded",
}

response = requests.request("GET", url, data=payload, headers=headers, auth=(client_id, client_secret))


print(response.text)

---

Azure AD Non-Production Host

This Azure AD host is used in the end to end OpenShift environment and the cipapi-gms-beta.gel.zone instance. The host is the central identity provider which is used for authentication.

Azure AD Host Information For Non-Prod/E2E/Alpha Release
----------------------------------------------------------------------------------------


Tenant ID:                afee026d-8f37-400e-8869-72d9124873e4
Tenant Name               ngisnonprod.onmicrosoft.com
Discovery Document URL    https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/.well-known/openid-configuration
Authorization End point   https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/authorize
Token Endpoint            https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/token
Key Endpoint              https://login.microsoftonline.com/common/discovery/keys
----------------------------------------------------------------------------------------

---

Azure AD Host Client Credentials Response Example

The JWT contains very little information about the application other than some basic info such as 'AppID' that can be used to perform authorisation. You can decode the access_token with any JWT decoder, e.g. https://jwt.io/

Example POST Response from AD Host

+-----------------------------------------------------------------------+
| {\                                                                    |
| "token\_type": "Bearer",\                                             |
| "expires\_in": "3600",\                                               |
| "ext\_expires\_in": "3600",\                                          |
| "expires\_on": "1554737233",\                                         |
| "not\_before": "1554733333",\                                         |
| "resource": "00000002-0000-0000-c000-000000000000",\                  |
| "access\_token":                                                      |
| "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik4tbEMwbi05REFMcXdodUhZ |
| bkhRNjNHZUNYYyIsImtpZCI6Ik4tbEMwbi05REFMcXdodUhZbkhRNjNHZUNYYyJ9.eyJh |
| dWQiOiIwMDAwMDAwMi0wMDAwLTAwMDAtYzAwMC0wMDAwMDAwMDAwMDAiLCJpc3MiOiJod |
| HRwczovL3N0cy53aW5kb3dzLm5ldC85OTUxNTU3OC1mZGEwLTQ0NGMtOGY1YS0yMDA1MD |
| M4ODgwZjIvIiwiaWF0IjoxNTU0NzMzMzMzLCJuYmYiOjE1NTQ3MzMzMzMsImV4cCI6MTU |
| 1NDczNzIzMywiYWlvIjoiNDJaZ1lIajRmbS9wMFgyVy95N2NmbFo4TGU3RVBnQT0iLCJh |
| cHBpZCI6IjQ1OTU0NjJhLWRjYjctNDE0ZC05Y2YxLTJjMzJiNzE4N2Y0MSIsImFwcGlkY |
| WNyIjoiMSIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0Lzk5NTE1NTc4LWZkYT |
| AtNDQ0Yy04ZjVhLTIwMDUwMzg4ODBmMi8iLCJvaWQiOiJiZGIzNzhmMi1kZGJhLTRiN2Q |
| tYjljMi1mMTEwNGY1ZGFmOGQiLCJzdWIiOiJiZGIzNzhmMi1kZGJhLTRiN2QtYjljMi1m |
| MTEwNGY1ZGFmOGQiLCJ0ZW5hbnRfcmVnaW9uX3Njb3BlIjoiRVUiLCJ0aWQiOiI5OTUxN |
| TU3OC1mZGEwLTQ0NGMtOGY1YS0yMDA1MDM4ODgwZjIiLCJ1dGkiOiJRNUlzTWluNURFT3 |
| lVMUY5amZBdUFBIiwidmVyIjoiMS4wIn0.jgVYfe6i8z-sZk\_Dj5BC0Rh83-8p3Dqu16 |
| eeTZZ8cPK6xBslBx5FSVW\_91XMefK5jLphdXGGOPc4N5MZI8CkOaNFZZYqYuiPQSXdts |
| aDLgmN-NvrguWBzGLR7vh9DSHaAPoBVWaxjHb6IYgQA0HQWKY5bWVxctF5bpvrUX7nazv |
| Wv3cG0Fv1xgyPvePyVEM1NmvMXqHTxpTLX\_-uLHOMUruQIek7rWdJ6ldA3jOFfxVVw2J |
| qSARLIsP2G0RwNOcDU3GSQ942nxyHzJ\_bhRprnMHzP5wXp9bHbaodrrTdKna7eSZsi-I |
| lw-E1y6qpm7Xzej0SbrqUX2DoWhXphT8MbA"\                                 |
| }                                                                     |
+=======================================================================+
+-----------------------------------------------------------------------+

Example Client Credentials JWT Access Token

+-----------------------------------------------------------------------+
| {                                                                     |
|                                                                       |
| "aud": "00000002-0000-0000-c000-000000000000",\                       |
| "iss":                                                                |
| "<https://sts.windows.net/99515578-fda0-444c-8f5a-2005038880f2/>",\   |
| "iat": 1554733333,\                                                   |
| "nbf": 1554733333,\                                                   |
| "exp": 1554737233,\                                                   |
| "aio": "42ZgYHj4fm/p0X2W/y7cflZ8Le7EPgA=",\                           |
| "appid": "4595462a-dcb7-414d-9cf1-2c32b7187f41",\                     |
| "appidacr": "1",\                                                     |
| "idp":                                                                |
| "<https://sts.windows.net/99515578-fda0-444c-8f5a-2005038880f2/>",\   |
| "oid": "bdb378f2-ddba-4b7d-b9c2-f1104f5daf8d",\                       |
| "sub": "bdb378f2-ddba-4b7d-b9c2-f1104f5daf8d",\                       |
| "tenant\_region\_scope": "EU",\                                       |
| "tid": "99515578-fda0-444c-8f5a-2005038880f2",\                       |
| "uti": "Q5IsMin5DEOyU1F9jfAuAA",\                                     |
| "ver": "1.0"\                                                         |
| }                                                                     |
+=======================================================================+
+-----------------------------------------------------------------------+

---

Practical Example on How to Use AD Client Credentials Flow and Communicating to CIP-API

Please go the following jupyter notebook to test how to access the CIP-API using client credentials AD auth flow: https://github.com/genomicsengland/ACGS_GeL_API_workshop/blob/master/gms_integration/gms_authentication.ipynb

---

Getting a token from CIP-API (Resource Owner Password Credentials Flow)

Before accessing your data you first need to obtain an authentication "token". Once you have authenticated and obtained a token you can query the API for your data

• URL V2: /api/2/get-token/
• Method: POST
• Content Type: “application/json”
• Content: {“username”: “user”, “password”: “password”}

Your username and password will have been issued by Genomics England Service Desk, for any issues please email: ge-servicedesk@genomicsengland.co.uk

Let's assume you have credentials stored in the following variables:

import os
CIP_API_USERNAME = os.getenv("CIP_API_USERNAME") or "your_username_here"
CIP_API_PASSWORD = os.getenv("CIP_API_PASSWORD") or "your_password_here"
CIP_API_SERVER_URL = os.getenv("CIP_API_SERVER_URL") or "https://cip-api-server-url/api/2/{endpoint}"

The get_url_json_response function below will return the json response from the url you provide (if successful) and will authenticate based on your credentials. The URL you provide can be any V1 or V2 endpoint along with the allowed parameters as shown in the Swagger UI of the CIP-API here: https://{cipapi-url}/api/2/docs/. However, your specific membership to groups in AD or in LDAP determine what level of authorisation you have in the CIP-API.

    import requests

    def get_authenticated_header():
        url = CIP_API_SERVER_URL
        auth_endpoint = "get-token/"

        irl_response = requests.post(
            url = CIP_API_SERVER_URL + auth_endpoint,
            json=dict(
                username=CIP_API_USERNAME,
                password=CIP_API_PASSWORD,
            ),
        )
        irl_response_json = irl_response.json()
        token = irl_response_json.get('token')

        auth_header = {
            'Accept': 'application/json',
            "Authorization": "JWT {token}".format(token=token),
        }
        return auth_header

    def get_url_json_response(url):
        response = requests.get(url=url, headers=get_authenticated_header())

        if response.status_code != 200:
            raise ValueError(
                "Received status: {status} for url: {url} with response: {response}".format(
                status=response.status_code, url=url, response=response.content)
            )
        return response.json()

---

NEW! Authorisation

Azure Active Directory User groups and Roles (GMS and 100K)

In 100K, all clinical users (Clinical Scientists and Clinical Managers at the GMC) can only see cases that are specific to their set of labs (local delivery partners, LDPs) in their respective GMC. This will remain the same. In NHS GMS, a Clinical Scientist and Clinical Manager can see any referral that belongs to their country (England, Wales, Northern Ireland, Scotland).

Depending on the attributes of the users, specific authorisation will be granted in the CIP-API, every user will have a role which will determine what can they get.

Only the following roles will be allowed to retrieve data from the CIP-API:

Role ID	Description	Notes
NCR003	Clinical Scientist	Ability to read from the bioinformatics applications (interpretation portal, CIP-API, OpenCGA, CVA) in GMS and also 100k if having particular attributes.
NCR004	Clinical Manager	Same permissions as NCR003 above.
NNR501	GEL Users	Internal Users to GeL.
NNR502	3rd Party Clinical User	DSSs, 3rd Party Interpretation Services (e.g. a real DSS user troubleshooting their system and front end from a test environment). Note: these users will have strict permissioning based on group membership.
NNR503	100K Legacy Users	These are users which will not be able to see any GMS cases, but will be part of new Azure AD instance. Only 100K data that is part of the LDPs of the "primaryLdpCode100k" and "secondaryLdpCodes100k" attributes will be available.
NNR504	NHS Management	This is a management role where everything is read only, but will be used for audit purposes.Currently undecided if bioinformatics audit is also required.

---

Azure Active Directory Client Credential Authorisation (GMS and 100K)

All systems which authenticate via client credentials flow will be uniquely registered in CIP-API, CVA, OpenCGA, etc. System accounts do not have any user attributes, such as Role (e.g. Clinical Scientist) or other attributes (e.g primaryEntityCodeNgis). Therefore, each GMS application will authorise these clients by their client appId or client oid from their JWT bearer token.

For example, a Gel2MDT system will have the following rights in the CIP-API: - GET all endpoints --> Retrieve any data in cipapi-gms-beta - POST clinical-report --> Add a summary of findings to a case - PUT exit-questionnaire --> Add an exit questionnaire to a case - PUT interpretation-request/{ir_id}/{ir_version}/snp_check/{sample_id} -->Re-run sample matching service for a given sample

---

NEW! Example: List of Interpretation Requests Endpoint

• URL V2:/api/2/interpretation-request
• Method:GET
• Content Type: “application/json”

The result of this endpoint is to present to the user a paginated overview of the list of cases they are allowed to inspect.

Use format to construct the full URL.

IR_list_url = CIP_API_SERVER_URL.format(endpoint=interpretation_request_list_endpoint)

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.

IR_list = get_url_json_response(url=IR_list_url)

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 case. 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 defined by GelReportModels. More information on GeLReportModels can be found in the background section here: Background: GeLReportModels

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:

interpretation_request_payload = case_data['interpretation_request_data']['json_request']

Example data retrieved from interpretation_request_data:

pedigree = interpretation_request_payload['pedigree']
genePanelsCoverage = interpretation_request_payload['genePanelsCoverage']

---

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)

---

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 MDT tool 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

>>>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']

---

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, clinica_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

>>>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

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 clinical_report can be found in the background section here: Background: Interpreted Genome

---

NEW! 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”

---

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.

IR_case_url = CIP_API_SERVER_URL.format(endpoint='interpretation-request/{ir_id}/{ir_version}/?extra-params=show_referral')
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)
referral = case_data['referral']

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

Background

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

The endpoint format: https://{host}/reidentification/ is the root address for each TOMS environment, where is the environment hostname

For example, for the TOMs beta environment, the following endpoints are available:

• https://api.beta.genomics.nhs.uk/reidentification/referral-pid
• https://api.beta.genomics.nhs.uk/reidentification/patient-pid

Retrieving PID with the NGIS GUID for a referral

• Query URL: https://api.beta.genomics.nhs.uk/reidentification/referral-pid
• 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.beta.genomics.nhs.uk/reidentification/referral-pid/<REFERRAL_ID>

where "{JWT}" is the JSON Web token and is the GUID of the referral for which you want to obtain PID information

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.beta.genomics.nhs.uk/reidentification/patient-pid/<PATIENT_ID>

where "{JWT}" is the JSON Web token and is the GUID of the patient for which you want to obtain PID information

Response:

{
 "ngis_uid": "9e6560fe-d9e8-a-8a39-ab50a7f092a4",
 "human_readable_id": "p75786904064",
 "name": "Ms CORA CROOKS",
 "date_of_birth": "2011-06-09",
 "nhs_number": "9449306265"
 }

---

API Statuses

Please see the table below with a brief description of each different API status given in the Genomics England Clinical Interpretation Platform API (CIP-API).

CIP-API status	Description
waiting_payload	Interpretation Pipeline has completed
interpretation_generated	Interpretation Request has been created, ready to send to DSS
snp_check_pending	(GMS-Rare Disease) The referral test's samples do not have a complete set of all sample matching service results
snp_check_pass	(GMS-Rare Disease) The referral test's samples have a complete set of all samples passing the sample matching service comparison
snp_check_fail	(GMS-Rare Disease) At least one sample from a referral test has failed the sample matching service comparison
files_copied	VCF and tiering files have been sent to the DSS
dispatched	Interpretation Request has been sent to DSS
transfer_ready	DSS has completed their analysis of the case
transfer_complete	DSS has transferred their interpreted genome to the API
gel_qc_failed	The case has failed GeL QC checks and will be sent back to the DSS
rejected_wrong_format	Interpreted Genome has failed API validation
gel_qc_passed	The case has passed GeL QC checks
sent_to_gmcs	The case has been sent to the GMCs for them to generate the report in the DSS portal in Inuvika/web interface
report_generated	A report/summary of findings has been generated for this case by the GMC. More than one report can be generated
report_sent	The latest report/summary of findings' outcomes exit questionnaire has been submitted by the user
blocked	interpretation of the case has been blocked

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.