CTS2-LE REST API: Resolve Value Set

This REST call fetches the full content of a defined value set or codesystem. In case a value set is requested, this call responds with the expanded content of the value set, which means that all code references are resolved from their underlying codesystems.

Operation Syntax

Signature

root: @Path("/fhir/ValueSet")

Response webCts2Le.rest.FhirValueSets.resolveValueSet(

@Context HttpServletRequest request,

@QueryParam(value="_query") String query,

@QueryParam(value="identifier") String valueset-URI,

@QueryParam(value="stylesheet") String stylesheet-path,

@QueryParam(value="limit") Integer max-count)

@GET

@Produces(value={"application/xml"})

REST Call Syntax

http://<host>/WebCts2LE/rest/fhir/ValueSet?_query=expandResource&identifier=<valueset-URI>&stylesheet=<stylesheet-path>&limit=<max-count>

Parameters

_query=expandResource

fixed parameter for signaling a query on a (potentially expandable) value set resource

Optionality: mandatory

identifier=<valueset-URI>

<valueset-URI>: URI-encoded identifier of the requested value set or codesystem

Optionality: mandatory

Cardinality: 1..1

Example: identifier=urn:oid:2.16.840.1.113883.5.1050

Example: identifier=http://hl7.org/fhir/vs/administrative-gender

stylesheet=<stylesheet-path>

<stylesheet-path>: stylesheet that will be referenced within the XML response

Optionality: optional

Cardinality: 0..1

limit=<max-count>

<max-count>: Maximum number of elements to be included with the result set. If this parameter is omitted, the full content of the requested value set or codesystem will be returned.

Optionality: optional

Cardinality: 0..1

Example: limit=100

Result

In case of an successful processing of the call, the result will an FHIR Value Set resource as defined in http://www.hl7.org/fhir/valueset.html containing the contents of the requested value set or codesystem.

In case of an error an empty FHIR Value Set resource is returned.

Example

The main purpose of the method is to resolve value sets in order to allow for

1. display value set items to the user
2. validation of code system/value set references of an electronic health record

In order to reference the value set properly, one has to use its identifier, e.g. http://hl7.org/fhir/vs/administrative-gender

This identifier has to be part of the http-call

http://<host>/WebCts2LE/rest/fhir/ValueSet?_query=expandResource&identifier=http://hl7.org/fhir/vs/administrative-gender

that will return the following value set expansion

<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://hl7.org/fhir"
   xmlns:at="http://purl.org/atompub/tombstones/1.0" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
   xmlns:os="http://a9.com/-/spec/opensearch/1.1/" xmlns:xhtml="http://www.w3.org/1999/xhtml"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <atom:title>Value Set Expansion</atom:title>
   <atom:id>urn:uuid:dc9f2f7e-6a1b-4389-9b88-7048787227c2</atom:id>
   <atom:updated>2015-04-05T13:46:55</atom:updated>
   <atom:entry>
      <atom:title>Value Set Resolution</atom:title>
      <atom:id>http://hl7.org/fhir/vs/administrative-gender</atom:id>
      <atom:updated>2015-04-05T13:46:55</atom:updated>
      <atom:content>
         <ValueSet xmlns="http://hl7.org/fhir">
            <name value="..." />
            <description value="..." />
            <status value="draft" />
            <expansion>
               <timestamp />
               <contains xmlns="http://hl7.org/fhir">
                  <system value="urn:oid:2.16.840.1.113883.5.1" />
                  <code value="F" />
                  <display value="Female" />
               </contains>
               <contains xmlns="http://hl7.org/fhir">
                  <system value="urn:oid:2.16.840.1.113883.5.1" />
                  <code value="M" />
                  <display value="Male" />
               </contains>
               <contains xmlns="http://hl7.org/fhir">
                  <system value="urn:oid:2.16.840.1.113883.5.1" />
                  <code value="UN" />
                  <display value="Undifferentiated" />
               </contains>
               <contains xmlns="http://hl7.org/fhir">
                  <system value="urn:oid:2.16.840.1.113883.5.1008" />
                  <code value="UNK" />
                  <display value="unknown" />
               </contains>
            </expansion>
         </ValueSet>
      </atom:content>
   </atom:entry>
</atom:feed>

Appropriate XPATH expressions should select the code list. E.g., the XPATH expression

/atom:feed/atom:entry/atom:content/ValueSet/expansion/contains

retrieves all (code, code system)-pairs with their display name.