CTS2-LE REST API: Read Code Systems and Code System Versions

Aus CTS2-LE
Zur Navigation springen Zur Suche springen

A general note on code systems (cs) and code system versions (csv): The underlying implementation of the CTS2 information model identifies a cs by its uri only. A specific version of a cs will then have its own name (resourceID wrt. the information model) and a versionId. A csv can be uniquely identified by the pair of versionOf and versionId. Since the resourceID is a system intern identifier, using it as a path parameter to identify a csv is not suitable. Because of that any call that a.) tries to reference a cs by its name rather than by its uri (versionOf) or b.) tries to reference a csv without specifying the version id and the uri will result in an exception.
Response format and language may be controlled either by a Query Parameter: ?referencelanguage={language} or ?format={format} OR by the HTTP 'Accept' and 'Accept-Language' Header Parameters. Query OR Header parameters will both be accepted as valid, however, the Query parameters will ALWAYS take precedence over the Header parameters, if both are present. Currently, we only support application/xml as format (except for the grouping calls). The language attribute will be ignored.


Root-URL: /WebCts2LE/rest/

Request all code system groups

  • does not belong to the standard CTS2 REST specification
  • Path: /codesystemgroups
  • Method: GET
  • Path Parameters: -
  • Query Parameters:
expanded boolean used to state whether group members should be retrieved (default is false)
  • withVersionIdAndUri boolean used to state whether versionOf and versionId-attributes of a codesystem version should be retrieved (default is false)
  • returns: an array in which each item represents a code system group
Example Response Structure

[
 {
     "name": "Example",
     "children": [
        {
           "name": "Codesystems",
           "relGroup": [
              "EXA",
              "not-exists"
           ],
           "_id": "64"
        }
     ],
     "_id": "61"
  }
]


Example Response Structure (with query parameter "expanded" set to true)

[
 {
     "name": "Example",
     "children": [
        {
           "name": "Codesystems",
           "relGroup": [
              "EXA",
              "not-exists"
           ],
           "_id": "64",
           "children": [
              {
                 "name": "ExampleCS2013",
                 "isLeaf": true
              },
              {
                 "name": "ExampleCS2016",
                 "isLeaf": true
              },
              {
                 "name": "classif-1",
                 "isLeaf": true
              },
              {
                 "name": "code-system-88",
                 "isLeaf": true
              },
              {
                 "name": "code-system-88-4-11",
                 "isLeaf": true
              },
              {
                 "name": "code-system-stu3-88",
                 "isLeaf": true
              }
           ]
        }
     ],
     "_id": "61"
  }
]

Example Response Structure (with query parameters "expanded" and "withVersionIdAndUri" set to true)

[
  {
     "name": "Example",
     "children": [
        {
           "name": "Codesystems",
           "relGroup": [
              "EXA",
              "not-exists"
           ],
           "_id": "64",
           "children": [
              {
                 "name": "ExampleCS2013",
                 "isLeaf": true,
                 "versionId": "1.0",
                 "versionOf": "example:terminology"
              },
              {
                 "name": "ExampleCS2016",
                 "isLeaf": true,
                 "versionId": "1.0",
                 "versionOf": "example:anotherTerminology"
              },
              {
                 "name": "classif-1",
                 "isLeaf": true,
                 "versionId": "2016-01-01",
                 "versionOf": "http://test/vs/classif-1"
              },
              {
                 "name": "code-system-88",
                 "isLeaf": true,
                 "versionId": "2015-11-01",
                 "versionOf": "http://test/vs"
              },
              {
                 "name": "code-system-88-4-11",
                 "isLeaf": true,
                 "versionId": "2016-04-11",
                 "versionOf": "http://test/vs"
              },
              {
                 "name": "code-system-stu3-88",
                 "isLeaf": true,
                 "versionId": "2017-01",
                 "versionOf": "http://test/stu3/cs"
              }
           ]
        }
     ],
     "_id": "61"
  }
]

Request code system versions (csv) for a given group id

  • does not belong to the standard CTS2 REST specification
  • Path: /codesystemgroup/{groupid}
  • Method: GET
  • Path Parameters:
groupid the id of the group whose items are requested; the id that is used to reference the group is given in the resulting array that is returned when calling /codesystemgroups
  • Query Parameters: -
  • returns: an array that contains the code system versions belonging to the requested group
Example Response Structure for call /codesystemgroup/64

[
 {
   "name": "ExampleCS2013",
   "isLeaf": true,
   "versionId": "1.0",
   "versionOf": "example:terminology"
 },
 {
   "name": "ExampleCS2016",
   "isLeaf": true,
   "versionId": "1.0",
   "versionOf": "example:anotherTerminology"
 },
 {
   "name": "ExampleMappingVersion1",
   "isLeaf": true,
   "versionId": "1.0",
   "versionOf": "example:mapping"
 },
 {
   "name": "ExampleMappingVersion2",
   "isLeaf": true,
   "versionId": "2.0",
   "versionOf": "example:mapping"
 },
 {
   "name": "classif-1",
   "isLeaf": true,
   "versionId": "2016-01-01",
   "versionOf": "http://test/vs/classif-1"
 },
 {
   "name": "code-system-88-4-11",
   "isLeaf": true,
   "versionId": "2016-04-11",
   "versionOf": "http://test/vs"
 }
]

Meaning of the entry properties:

  • name: the resourceID of the code system version (see CTS2 information model for further reference)
  • isLeaf: true if there are no subordinated code system versions
  • versionId: the versionId that is used to reference the code system version (see CTS2 information model for further reference)
  • versionOf: the uri of the code system that this specific version belongs to (see CTS2 information model for further reference)
Exceptions
  • UnknownGroup if there is no group with the given groupId

Retrieve the specified code system version details

  • Path: /codesystem/{codesystemid}/version/{codesystemversionid}
  • Method: GET
  • Path Parameters:
codesytemid the Name of the Code System - needs to be set to an underscore '_'
codesystemversionid If the query parameter codesystemuri is given, the value of this parameter defines the version ID (set to '_def' to request the default version); if the query parameter codesystemuri is NOT given, the value of this parameter refers to the unique resourceID of the code system version
  • Query Parameters:
codesystemuri the URI that references the code system, e.g. http://www.nlm.nih.gov/mesh14 for the MeSH vocabulary; use this query parameter in conjunction with the path parameter codesystemversionid when the latter refers to the versionID of the requested code system version the URI that references a code system, e.g. http://www.nlm.nih.gov/mesh14 for the MeSH vocabulary
  • returns:
codeSystemVersion:CodeSystemVersionCatalogEntryMsg This service implementation uses the property element to designate whether the requested code system version is the default version. The codesystemversionid is provided by the officialResourceVersionId element.

CodeSystemVersionCatalogReadService:read: Retrieve the specified code system version details from the service. This call can be used in the following manners: a.) A code system version may be identified by means of its uri and its codesystemversionid. The first path parameter should then be replaced by an underscore '_' and a query parameter called "codesystemuri" should be specified. e.g. the 2014 version of the Medical Subject Headings can be identified through its URI which is "http://www.nlm.nih.gov/mesh14" and the codesystemversionid "2014". The request would then be structured as follows: /codesystem/_/version/2014?codesystemuri=http://www.nlm.nih.gov/mesh14
If the client wants to request the default version of a code system, he or she requests the resource by setting the codesystemversionid to '_def' and the codesystemuri as query param. e.g. the default version of the Medical Subject Headings can be requested as follows: /codesystem/_/version/_def?codesystemuri=http://www.nlm.nih.gov/mesh14.
b.) A code system version may be fetched by its unique name (resourceID). The first path parameter codesystemid should be replaced by an underscore '_'. The second path parameter codesystemversionid refers to the resourceID. The query parameter codesystemuri should be omitted.


Example Responses
A.) Get CSV by uri and versionID

Get CSV with uri example:terminology and versionId 1.0
Path: /codesystem/_/version/1.0?codesystemuri=example:terminology 

<?xml version="1.0" encoding="UTF-8"?>
<CodeSystemVersionCatalogEntryMsg xmlns="http://www.omg.org/spec/CTS2/1.1/CodeSystemVersion" xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <core:heading xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>codesystem/_/version/1.0</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:parameter arg="Accept-Language">
           <core:val>de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4</core:val>
       </core:parameter>
       <core:parameter arg="codesystemuri">
           <core:val>example:terminology</core:val>
       </core:parameter>
       <core:accessDate>2016-07-04T14:42:45</core:accessDate>
   </core:heading>
   <codeSystemVersionCatalogEntry xmlns="http://www.omg.org/spec/CTS2/1.1/CodeSystemVersion" codeSystemVersionName="ExampleCS2013" about="UNKNOWN">
       <core:note xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
           <core:value>this is an example codesystem</core:value>
       </core:note>
       <core:property xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
           <core:predicate uri="http://fokus.fraunhofer.de/eHealth/cts2infoModel/signatures#isDefaultVersion">
               <core:name>isDefaultVersion</core:name>
           </core:predicate>
           <core:value>
               <core:literal>
                   <core:value>true</core:value>
               </core:literal>
           </core:value>
       </core:property>
       <core:alternateID xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">example:terminology</core:alternateID>
       <core:officialResourceVersionId xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">1.0</core:officialResourceVersionId>
       <versionOf uri="example:terminology">UNKNOWN</versionOf>
       <defaultLanguage>en</defaultLanguage>
       <entityDescriptions>http://localhost:8080/WebCts2LE/rest/codesystem/_/version/1.0/entities?codesystemuri=example:terminology</entityDescriptions>
   </codeSystemVersionCatalogEntry>
</CodeSystemVersionCatalogEntryMsg>

B.) Get CSV by resourceID

Get CSV with resourceID ExampleCS2013
Path: /codesystem/_/version/ExampleCS2013

<?xml version="1.0" encoding="UTF-8"?>
<CodeSystemVersionCatalogEntryMsg xmlns="http://schema.omg.org/spec/CTS2/1.0/CodeSystemVersion" xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <core:heading xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>codesystem/_/version/ExampleCS2013</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:accessDate>2017-12-19T09:31:02</core:accessDate>
   </core:heading>
   <codeSystemVersionCatalogEntry xmlns="http://schema.omg.org/spec/CTS2/1.0/CodeSystemVersion" documentURI="UNKNOWN" codeSystemVersionName="ExampleCS2013" about="urn:negros:oid#_2D1c8da8d9_3A1606ddda6ff_3A_2D7fff">
       <core:note xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">
           <core:value>this is an example codesystem</core:value>
       </core:note>
       <core:property xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">
           <core:predicate uri="http://fokus.fraunhofer.de/eHealth/cts2infoModel/signatures#isDefaultVersion">
               <core:name>isDefaultVersion</core:name>
           </core:predicate>
           <core:value>
               <core:literal>
                   <core:value>true</core:value>
               </core:literal>
           </core:value>
       </core:property>
       <core:sourceAndNotation xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core" />
       <core:officialResourceVersionId xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">1.0</core:officialResourceVersionId>
       <versionOf uri="example:terminology">UNKNOWN</versionOf>
       <defaultLanguage>en</defaultLanguage>
       <entityDescriptions>http://localhost:8080/WebCts2LE/rest/codesystem/_/version/ExampleCS2013/entities</entityDescriptions>
   </codeSystemVersionCatalogEntry>
</CodeSystemVersionCatalogEntryMsg>

[non-public] Get default LOINC csv

Complete Path: http://10.147.147.61:8082/WebCts2LE/rest/codesystem/_/version/2.44?codesystemuri=urn:oid:2.16.840.1.113883.6.1 

<?xml version="1.0" encoding="UTF-8"?>
<CodeSystemVersionCatalogEntryMsg xmlns="http://www.omg.org/spec/CTS2/1.1/CodeSystemVersion" xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <core:heading xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
       <core:resourceRoot>http://10.147.147.61:8082/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>codesystem/_/version/2.44</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:parameter arg="codesystemuri">
           <core:val>urn:oid:2.16.840.1.113883.6.1</core:val>
       </core:parameter>
       <core:accessDate>2017-06-15T09:35:15</core:accessDate>
   </core:heading>
   <codeSystemVersionCatalogEntry xmlns="http://www.omg.org/spec/CTS2/1.1/CodeSystemVersion" codeSystemVersionName="Loinc2.44" about="UNKNOWN">
       <core:note xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
           <core:value>The LOINC system (Logical Observation Identifiers Names and Codes) is a universal code system that faciliates exchange, pooling and processing of clinical and laboratory test results.</core:value>
       </core:note>
       <core:property xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
           <core:predicate uri="http://fokus.fraunhofer.de/eHealth/cts2infoModel/signatures#isDefaultVersion">
               <core:name>isDefaultVersion</core:name>
           </core:predicate>
           <core:value>
               <core:literal>
                   <core:value>true</core:value>
               </core:literal>
           </core:value>
       </core:property>
       <core:alternateID xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">http://loinc.org</core:alternateID>
       <core:officialResourceVersionId xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">2.44</core:officialResourceVersionId>
       <versionOf uri="urn:oid:2.16.840.1.113883.6.1">UNKNOWN</versionOf>
       <defaultLanguage>en</defaultLanguage>
       <entityDescriptions>http://10.147.147.61:8082/WebCts2LE/rest/codesystem/_/version/2.44/entities?codesystemuri=urn:oid:2.16.840.1.113883.6.1</entityDescriptions>
   </codeSystemVersionCatalogEntry>
</CodeSystemVersionCatalogEntryMsg>

Exceptions
  • UnknownCodeSystemVersion if
    • the name of the code system (path parameter codesystemid) is not set to an underscore
    • the query parameter codesystemuri is given but is not a valid uri
    • there is no csv with the given uri and version id
    • there is no csv with the given resourceID
Abgerufen von „https://websites.fraunhofer.de/CTS2-LE/index.php?title=CTS2-LE_REST_API:_Read_Code_Systems_and_Code_System_Versions&oldid=1064“