Skip to content

API Changes

Jump to bottom
James Fleming edited this page May 28, 2021 · 20 revisions

This document is a work in progress for describing the API changes to the Submissions Service between the initial closed preview up to the initial public release.

Contents

Environment URLs

The public release will include Test and Production URLs that differ from the closed preview environments.

  • TBC

Auth process

The process for acquiring access tokens is changing slightly.

  • [AB#32498] The token issuing endpoint has moved, and tokens now expire:
    • To request an access token, now go to /token on the same base URL as the rest of the API endpoints.
      • not /identity anymore
      • not at a different base URL anymore
    • If a 401 is received even when a Bearer Token is provided, the client should hit the /token endpoint again with its credentials.
      • If successful, it should be able to proceed, retrying its previous operation with the new Bearer Token.
      • If unsuccessful (401 at /token), the credentials are no longer valid and new ones will be required.
  • TBC: How to get credentials?
    • [AB#32636] TDCC Development Staff have access to tooling to create credentials and can provide them on request.
    • Directory UI work is under consideration to achieve this without TDCC team support.

HTTP Response Codes

The following endpoints now return new or different HTTP response codes

Endpoint Old Code New Code Notes
/commit 204 No Content 202 Accepted On successful commit request

Submissions Schema

  • EXPAND: PreservationType - depends on StorageTemperature

ExtractionProcedure

An Extraction Procedure can be added to a sample to describe how the sample was obtained. Extraction Procedures are a specific subset of OntologyTerms (which can be found where?). Extraction Procedures only apply to certain Material Types (which ones?), and tagging a sample with the incorrect Material Type and Extraction Procedure pair will result in a validation error.

By default, the applicable Extraction Procedure is referenced by it's OntologyTerm ID.

"sample": {
    "materialType": "Tissue specimen",
    "extractionProcedure": "86273004",
    "extractionProcedureOntologyField": "Code"  //Assumed By Default
}

To reference the ExtractionProcedure via its value, use the Description OntologyField flag.

"sample": {
    "materialType": "Tissue specimen",
    "extractionProcedure": "Biopsy (procedure)",
    "extractionProcedureOntologyField": "Description"
}

AgeAtDonation

An AgeAtDonation value can be added to a sample to describe the age of the individual when the sample was collected. This property will now store the value as an ISO duration string. If the AgeAtDontation value is not added, one will be calculated from the Sample’s YearOfBirth property.

If an integer is used as the AgeAtDonation value, it will be converted to an ISO duration string with the value being interpreted in years. Otherwise, a valid ISO duration string will need to be passed. The following example represents a value of 5 years and 6 months.

"sample": {
    "ageAtDonation": "P5Y6M"
}

In order to pass a negative ISO duration, you must prepend a hyphen to the string.

"sample": {
    "ageAtDonation": "-P5Y6M"
}

Other process changes

Reference Data values

Most of the reference data changes were introduced in #149

MaterialTypes

The following new MaterialTypes have been introduced

Id Value
27 (Breast) Milk
28 Amniotic Fluid
29 Ascites Fluid
30 Bile
31 Body Cavity Fluid
32 Bone
33 Bone marrow aspirate
34 Bone Marrow Plasma
35 Bronchoalveolar lavage
36 Buffy coat
37 Cord blood
38 Dental pulp PLP
39 Entire body organ
40 Fetal tissue
41 Fibroblasts
42 Gas, exhaled (=breath)
43 Gastric Fluid
44 Hair
45 Menstrual blood
46 Nail
47 Nasal washing
48 Pericardial Fluid
49 Placenta
50 Pleural fluid PFL
52 Proteins
53 Red blood cells
54 Semen
55 Stem cells and iPS cells
56 Sweat
57 Teeth
58 Umbilical cord
59 Urine sediment
60 Vitreous Fluid

The following existing MaterialTypes have been renamed

Id Old Value New Value
7 Pathogen Isolated Pathogens
8 Peripheral blood cells Peripheral blood mononuclear cells (PBMC)
14 Tissue Tissue specimen
18 Bone marrow Whole bone marrow
20 Swabs Swab
21 Mucus Sputum
22 Blood Spots Dried whole blood (e.g. Guthrie cards) DWB

The following MaterialTypes have been deprecated. A suggested replacement type is provided

Deprecated Id Deprecated Value Replacement Id Replacement Value
3 Core biopsy 14 Tissue specimen

OntologyTerms

Additional OntolgoyTerms have been introduced

Id Value
201618014 Benign neoplasm of oesophagus
342581000000000 Retinal pigment epithelial dystrophy
72781000000000 Arthrofibrosis
20191016 Gestational diabetes mellitus
40121000000000 Retinal dystrophy due to systemic disorder
156370009 Psoriatic arthritis (disorder)
737540008 Trisomy 13 (morphologic abnormality)
1240750000000000 COVID-19
35531000000000 Dystrophy of sensory retina
482550013 Malignant tumour of lingual tonsil
482603012 Malignant tumour of oesophagus
203082005 Fibromyalgia (disorder)
201640017 Carcinoma in situ of oesophagus
384321000000000 Preterm infant status (observable entity)
768473009 Purine rich element binding protein A syndrome (disorder)
725894000 Influenza virus (organism)

Storage Temperature

The following StorageTemperatures have been introduced

Id Value
7 Liquid nitrogen vapor phase

The following StorageTemperatures have been renamed

Id Old Value New Value
1 RT (Room Temperature) RT
5 LN (Liquid Nitrogen) Liquid nitrogen liquid phase

PreservationType

A new type, PreservationType has been introduced to describe the way some samples have been preserved.

Id Value Applicable Storage Temperature
1 Paraffin RT
2 Resin (EM) RT
3 Resin (LM) RT

ExtractionProcedure

A new type, ExtractionProcedure has been introduced to describe how some samples have been obtained.

Id Value Applicable MaterialType
1 Excision Tissue specimen
2 Biopsy Tissue specimen

Backward Compatibility

TODO:

  • StorageTemperature

    • Concept: We want to accept older StorageTemperature values and map them to the newer StorageTemp + PreservationType values
    • Implementation: This should be done in the Submissions Processing worker (e.g. SampleValidationService)
    • Data: See AB#32516

  • MaterialType

    • Concept: We want to accept older MaterialTypes values and map them to the newer MaterialType + PreservationType values
    • Implementation: This should be done in the Submissions Processing worker (e.g. SampleValidationService)
    • Data: See AB#32517

Clone this wiki locally