...
Below is the abreviated representation of a section identified by the URI https://sdp-v.services.cdc.gov/api/sections/S-101 (omissions are indicated by ...):
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
...
"sectionId": "S-101",
"sectionName": "Complications Repeating Group",
"sectionUri": "/api/sections/S-101?version=1",
"version": 1,
"published_by": {
"id": 11,
"email": "ikk1@cdc.gov",
"created_at": "2017-12-18T17:16:14.159Z",
"updated_at": "2018-08-30T18:13:03.465Z",
...
},
"tags": [
{
"code": "Pilot-test Mumps v1.0",
"codeSystem": "",
"displayName": "MMG Name"
},
...
],
"nested_items": [
{
"question": {
"questionId": "Q-1167",
"questionText": "Type of Complication",
"questionUri": "/api/questions/Q-1167?version=1",
"version": 1,
"published_by": {
"id": 11,
"email": "ikk1@cdc.gov",
"created_at": "2017-12-18T17:16:14.159Z",
"updated_at": "2018-08-30T18:13:03.465Z",
...
},
...
"responseType": "Choice",
"tags": [
{
"code": "67187-5",
"codeSystem": "LN",
"displayName": "Data Element Identifier"
}
]
},
"response": {
"url": "/api/valueSets/RS-2753?version=2",
"id": "RS-2753",
"identifier": [
{
"system": "urn:ietf:rfc:3986",
"value": "urn:oid:2.16.840.1.114222.4.11.7474"
}
],
"version": 2,
"name": "Type of Complication (VZ)",
"status": null,
"description": "Update based on new MMG guide",
"publisher": "PHIN_VADS",
"expansion": {
...
"contains": [
{
"system": "2.16.840.1.113883.6.96",
"code": "186509002",
"display": "Postvaricella encephalitis (disorder)"
},
{
"system": "2.16.840.1.113883.6.96",
"code": "233604007",
"display": "Pneumonia (disorder)"
},
...
]
},
...
},
...
},
...
]
} |
Items of note:
- While the URI used to obtain the section representation (
https://sdp-v.services.cdc.gov/api/sections/S-101) did not include a version qualifier, the returned representation includes a canoncial identifier that does (/api/sections/S-101?version=1). While version 1 is the latest version of this section, the two URIs are equivalent but if a new version of the section is created the URI without the version qualifier will refer to the new version (a floating reference) while the canonical URI will always reference a version 1 of the section. - As per the guidance on HATEOAS, the representation contains links to other resources rather than reuiring clients to construct their own URIs based on knowledge of the URI structure used by the service, e.g.
/api/questions/Q-1167?version=1identifies one of the questions included in the section. - The section representation includes detailed information about the other resources that are linked to it (e.g. the question), this allows clients to get all the information they need in a single request rather than having to get the section then make additional requests to get information about questions included in the section.
...