Concept Reference Term API

Feed

The feed for concept reference terms could be found at http://host_name_for_tr/openmrs/ws/atomfeed/conceptreferenceterm/recent. A detailed description of atom feed for the TR server could be found here. Once the atom feed client finds a new entry on the feed, it should fetch the concept reference term from the server to take appropriate action. The URL to fetch the concept reference term is published inside the content section of the feed entry. The URL does not contain host information and the client has to pre-pend the hostname for the TR server to fetch the data.

Structure of the data

The URL for fetching the concept reference term published through the Atom Feed is /openmrs/ws/rest/v1/conceptreferenceterm/a580061a-2e3b-4936-b232-cb5c2ec308fd?v=custom:(uuid,name,conceptSource,description,code,version,retired,conceptReferenceTermMaps). Using this URL, a concept reference term could be fetched from the TR server.

The following listing shows a sample concept reference term fetched using the url mentioned above. 

<?xml version="1.0" encoding="UTF-8"?>
<object>
 <uuid>a580061a-2e3b-4936-b232-cb5c2ec308fd</uuid>
 <name>Viral pneumonia 206925</name>
 <conceptSource>
     <uuid>30601597-21d1-4bcd-a617-71955219276b</uuid>
     <display>ICD10-BD</display>
     <name>ICD10-BD</name>
     <description>ICD10 Codes for Bangladesh</description>
     <hl7Code>ICD10-BD</hl7Code>
     <retired>false</retired>
     <links>
       <link>
         <rel>self</rel>
         <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptsource/30601597-21d1-4bcd-a617-71955219276b</uri>
       </link>
     <link>
       <rel>full</rel>
       <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptsource/30601597-21d1-4bcd-a617-71955219276b?v=full</uri>
     </link>
    </links>
   <resourceVersion>1.8</resourceVersion>
 </conceptSource>
 <description>Viral pneumonia, unspecified Excl.: 206925</description>
 <code>J19.206925</code>
 <version>1.0</version>
 <retired>false</retired>
 <conceptReferenceTermMaps>
    <conceptreferencetermmap>
      <uuid>9ed7304e-ebe0-4d48-94b4-a4c2cc0b2c80</uuid>
      <display>ICD10-BD: J19.600148 - ICD10-BD: B00</display>
      <termA>
        <uuid>8053f717-5b7c-484e-81bf-7d3e577fbefd</uuid>
        <display>ICD10-BD: J19.600148 (IViral pneumonia, unspecified)</display>
        <links>
          <link>
            <rel>self</rel>
            <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptreferenceterm/8053f717-5b7c-484e-81bf-7d3e577fbefd</uri>
          </link>
        </links>
      </termA>
      <termB>
        <uuid>f8145ea8-4d68-4cce-8eed-2ec9232377a6</uuid>
        <display>ICD10-BD: B00 (Herpesviral Infection)</display>
        <links>
          <link>
             <rel>self</rel>
             <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptreferenceterm/f8145ea8-4d68-4cce-8eed-2ec9232377a6</uri>
          </link>
       </links>
     </termB>
     <conceptMapType>
        <uuid>35543629-7d8c-11e1-909d-c80aa9edcf4e</uuid>
        <display>SAME-AS</display>
        <links>
          <link>
            <rel>self</rel>
            <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptmaptype/35543629-7d8c-11e1-909d-c80aa9edcf4e</uri>
          </link>
       </links>
    </conceptMapType>
    <links>
      <link>
        <rel>self</rel>
        <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptreferencetermmap/9ed7304e-ebe0-4d48-94b4-a4c2cc0b2c80</uri>
      </link>
      <link>
        <rel>full</rel>
        <uri>http://172.18.46.53:9080/openmrs/ws/rest/v1/conceptreferencetermmap/9ed7304e-ebe0-4d48-94b4-a4c2cc0b2c80?v=full</uri>
     </link>
    </links>
    <resourceVersion>1.9</resourceVersion>
   </conceptreferencetermmap>
 </conceptReferenceTermMaps>
</object>

Field description

• uuid: A unique identifier that refers to the concept reference term in the server
• name: A human readable name for the concept reference term
• description: A human readable description for the concept reference term
• code: A string that specifies the code that refers to the concept reference term uniquely in any coding system
• version: The current version of the concept reference term
• retried: Whether the concept reference term is retired or not.
• concept source: The source or the namespace under which the reference term is defined.
  • uuid: A unique identifier that refers to the concept source in the server
  • display: A human readable name for the concept source
  • name: A human readable name for the concept source with the the source could also be searched.
  • description: A human readable description for the concept source
  • hl7code: A string that specifies the code for the concept source as specified by HL7
  • retired: Whether the concept source is retired or not
  • links: A set of related entities to the current concept source
    • link: Describes an entity and its relation to the concept source
      • rel: The type of relationship
      • uri: The URI using which the entity can be fetched from the server
  • resourceVersion: The version of the Concept Source API
• conceptReferenceTermMaps: Specifies a set of concept reference terms that are related to the current concept reference term as defined in the coding standard.
  • conceptReferenceTermMap: Describes the mapping between the concept reference term and another concept reference term. The related reference term could be from the same source or a different source
    • uuid: A unique identifier that refers to the concept reference term map entity in the server.
    • display: A human readable description of the concept reference term map
    • termA: The Current reference term
      • uuid: A unique identifier that refers to termA on the server
      • display: A human readable name for termA on the server
      • links: A set of related entities to termA
        • link: Describes an entity and its relation to termA
          • rel: The type of relationship
          • uri: The URI using which the entity can be fetched from the server
    • termB: The reference term to which the current reference term is related to
      • uuid: A unique identifier that refers to termB on the server
      • display: A human readable name for termB on the server
      • links: A set of related entities to termB
        • link: Describes an entity and its relation to termB
          • rel: The type of relationship
          • uri: The URI using which the entity can be fetched from the server
    • conceptMapType: Specifies the type of mapping between the current reference term and the related term
      • uuid: A unique identifier that refers to the concept map type on the server
      • display: A human readable name for the concept map type
• links: A set of related entities to the concept reference term
  • link: Describes an entity and its relation to the concept reference term
    • rel: The type of relationship
    • uri: The URI using which the entity can be fetched from the server
• resourceVersion: The version of the concept reference term API

It is important to note that each reference term data is self contained, ie, related entities like concept source are embedded into the document. It is the responsibility of the client to check whether the concept source already exists in the local database and refer to it if it exists rather than creating a new entry.  Also the same data is returned when the concept reference term is being fetched because it was edited on the server. It is the responsibilty of the client to merge the new data with the existing concept reference term data in the local database.