CTS2-LE REST API: Read Value Set Definitions

Aus CTS2-LE
Zur Navigation springen Zur Suche springen

A general note on value sets (vs) and value set definitions (vsd): The underlying implementation of the CTS2 information model identifies a vs by its uri only. A specific definition of a vsd will then have its own name (resourceID wrt. the information model) and a versionId. A vsd 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 vsd is not suitable. Because of that any call that a.) tries to reference a vs by its name rather than by its uri (versionOf) or b.) tries to reference a vsd 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 value set groups

  • does not belong to the standard CTS2 REST specification
  • Path: /valuesetgroups
  • 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 value set definition should be retrieved (default is false)
  • returns: an array in which each item represents a value set group
Example Response Structure

[
 {
   "name": "FHIR",
   "relGroup": "FHIR-vs",
   "_id": "82"
 },
 {
   "name": "HL7-v3",
   "relGroup": "HL7-v3-vs",
   "_id": "86"
 },
 {
   "name": "Example",
   "relGroup": "EXA-vs",
   "_id": "94"
 },
 {
   "name": "EFAv2.x",
   "relGroup": "EFAv2.x-vs",
   "_id": "98"
 }
]


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

[
 {
   "name": "FHIR",
   "relGroup": "FHIR-vs",
   "_id": "82"
 },
 {
   "name": "HL7-v3",
   "relGroup": "HL7-v3-vs",
   "_id": "86"
 },
 {
   "name": "Example",
   "relGroup": "EXA-vs",
   "_id": "94",
   "children": [
     {
       "name": "value-set-99",
       "isLeaf": true
     },
     {
       "name": "value-set-stu3-99",
       "isLeaf": true
     }
   ]
 },
 {
   "name": "EFAv2.x",
   "relGroup": "EFAv2.x-vs",
   "_id": "98"
 }

]

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

[
 {
   "name": "FHIR",
   "relGroup": "FHIR-vs",
   "_id": "82"
 },
 {
   "name": "HL7-v3",
   "relGroup": "HL7-v3-vs",
   "_id": "86"
 },
 {
   "name": "DEMIS",
   "relGroup": "DEMIS-vs",
   "_id": "90"
 },
 {
   "name": "Example",
   "relGroup": "EXA-vs",
   "_id": "94",
   "children": [
     {
       "name": "value-set-99",
       "isLeaf": true,
       "versionId": "2014-11-01",
       "versionOf": "urn:oid:1.2.3.4"
     },
     {
       "name": "value-set-stu3-99",
       "isLeaf": true,
       "versionId": "2017-01",
       "versionOf": "http://test/stu3/vs"
     }
   ]
 },
 {
   "name": "EFAv2.x",
   "relGroup": "EFAv2.x-vs",
   "_id": "98"
 }

]

Request value set definitions (vsd) for a given group id

  • does not belong to the standard CTS2 REST specification
  • Path: /valuesetgroup/{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 /valuesetgroups
  • Query Parameters: -
  • returns: an array that contains the value set definitions belonging to the requested group
Example Response Structure for call /valuesetgroup/94

[ 

 {
   "name": "value-set-99",
   "isLeaf": true,
   "versionId": "2014-11-01",
   "versionOf": "urn:oid:1.2.3.4"
 },
 {
   "name": "value-set-stu3-99",
   "isLeaf": true,
   "versionId": "2017-01",
   "versionOf": "http://test/stu3/vs"
 }

]]

Meaning of the entry properties:

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


Retrieve the specified value set definition details

  • Path: /valueset/{valuesetid}/definition/{valuesetdefinitionid}
  • Method: GET
  • Path Parameters:
valuesetid the Name of the Value Set - will be ignored
valuesetdefinitionid if the query parameter valueseturi is given, the value of this parameter defines the version ID (set to '_def' to request the default version); if the query parameter valueseturi is NOT given, the value of this parameter refers to the unique resourceID of the value set definition
  • Query Parameters:
valueseturi the URI that references the value set; use this query parameter in conjunction with the path parameter valuesetdefinitionid when the latter refers to the versionID of the requested value set definition
  • returns:
valueSetDefinition:ValueSetDefinitionMsg

Note: Currently, the underlying CTS2 information model only allows to represent value set definitions that either reference a complete codesystem or a list of specific entities. For the latter, there is no proper way to specify the codesystem the entities belong to. However, this information is crucial when it comes to resolving the value set. Because of that, we use the uri attribute of a referenced entity (complete path would be ValueSetDefinitionMsg, valueSetDefinition, entry, entityList, referencedEntity) to reference the code system by its uri. If entities are drawn from a non-default codesystemversion, the versionId will be appended after the code system uri, separated by an '#'. (see the second example response structure)

ValueSetDefinitionReadService:read: Retrieve the specified value set definition. Retrieve the specified value set definition details from the service. This call can be used in the following manners: a.) A value set definition can be fetched by its uri and valuesetdefinitionid. The first path parameter (valuesetid) should then be replaced by an underscore '_' and a query parameter called "valueseturi" should be specified. If the client wants to request the default value set definition, he or she requests the resource by setting the parameter valuesetdefinitionid to '_def' and the valueseturi as query param. 2.) A value set definition can be fetched by its unique name (resourceID). The first path parameter valuesetid then needs to be replaced by an underscore '_'. The second path parameter valuesetdefinitionid refers to the resourceID. The query parameter valueseturi should be omitted.


Example Responses

API Call

  • a.) fetch by uri and valuesetdefinitionid: /valueset/_/definition/2014-11-01?valueseturi=urn:oid:1.2.3.4
  • b.) fetch by resourceID: /valueset/_/definition/value-set-99

The responses of a and b only differ in terms of the <core:heading>-element. 

<?xml version="1.0" encoding="UTF-8"?>
<ValueSetDefinitionMsg xmlns="http://www.omg.org/spec/CTS2/1.1/ValueSetDefinition" 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>valueset/_/definition/2014-11-01</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:parameter arg="valueseturi">
           <core:val>urn:oid:1.2.3.4</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:accessDate>2016-07-20T10:42:38</core:accessDate>
   </core:heading>
   <valueSetDefinition xmlns="http://www.omg.org/spec/CTS2/1.1/ValueSetDefinition" about="UNKNOWN">
       <core:officialResourceVersionId xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">2014-11-01</core:officialResourceVersionId>
       <definedValueSet uri="urn:oid:1.2.3.4">value-set-99</definedValueSet>
       <entry entryOrder="1" operator="UNION">
           <entityList>
               <referencedEntity uri="example:terminology">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">a01</core:name>
               </referencedEntity>
               <referencedEntity uri="example:terminology">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">b01</core:name>
               </referencedEntity>
           </entityList>
       </entry>
       <entry entryOrder="2" operator="UNION">
           <completeCodeSystem>
               <codeSystem uri="http://test/vs" />
           </completeCodeSystem>
       </entry>
   </valueSetDefinition>
</ValueSetDefinitionMsg>

API Call

  • a.) fetch by uri and valuesetdefinitionid: /valueset/_/definition/_def?valueseturi=urn:oid:1.2.276.0.76.3.1.163.11.110
  • b.) fetch by resourceID: /valueset/_/definition/DEMIS-vs-MethodCLO

The responses of a and b only differ in terms of the <core:heading>-element. Please note that the codesystemversion is referenced by means of the uri-attribute of each referencedEntity. In contrast to the upper example, a versionId is given and thus appended to the resourceUri and separated by a '#'. 

<?xml version="1.0" encoding="UTF-8"?>
<ValueSetDefinitionMsg xmlns="http://www.omg.org/spec/CTS2/1.1/ValueSetDefinition" 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>valueset/_/definition/_def</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:parameter arg="valueseturi">
           <core:val>urn:oid:1.2.276.0.76.3.1.163.11.110</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:accessDate>2016-07-20T12:59:48</core:accessDate>
   </core:heading>
   <valueSetDefinition xmlns="http://www.omg.org/spec/CTS2/1.1/ValueSetDefinition" about="UNKNOWN">
       <core:note xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
           <core:value>MethodCLO</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:officialResourceVersionId xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">14-01</core:officialResourceVersionId>
       <definedValueSet uri="urn:oid:1.2.276.0.76.3.1.163.11.110">DEMIS-vs-MethodCLO</definedValueSet>
       <entry entryOrder="1" operator="UNION">
           <entityList>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0093</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0096</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0178</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0179</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0180</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0181</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0278</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0286</core:name>
               </referencedEntity>
               <referencedEntity uri="urn:oid:1.2.276.0.76.3.1.163.5.12#14-01">
                   <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">Method0428</core:name>
               </referencedEntity>
           </entityList>
       </entry>
   </valueSetDefinition>
</ValueSetDefinitionMsg>

Exceptions
  • UnknownValueSetDefinition if
    • there is no valuesetdefinition with the given valueseturi and valuesetdefinitionId
    • there is no valuesetdefinition with the given resourceID
Abgerufen von „https://websites.fraunhofer.de/CTS2-LE/index.php?title=CTS2-LE_REST_API:_Read_Value_Set_Definitions&oldid=1073“