RxTerms RESTful Web API User's Guide

updated: 1/11/2012

The RxTerms RESTful API is a web service for accessing the current RxTerms data set.

Useful links:

Introduction

This document details the RxTerms RESTful web API, an alternative web service developed at the National Library of Medicine for the RxTerms data from the SOAP-based RxTerms API web services. Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of "representations" of "resources". A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.

The RxTerms RESTful web API is a simple web service implemented using HTTP and can be thought of as a collection of resources, specified as URIs. Some characteristics of the RxTerms RESTful web API:

The base URI for the web service is http://rxnav.nlm.nih.gov/REST/RxTerms
The web service supports a MIME type of XML, that is, the data is returned in XML format. The schema file that describes the XML format is located here. The web service can alternatively return the data in JSON or plain text format.
The web service only supports the HTTP method GET, since the web service function is to retrieve RxTerms data.

This document will define the valid resources for the RxTerms RESTful web API and provide the representations of the responses to these resource requests. Examples will be present throughout this document to provide a greater understanding of these interactions.

Clients

Clients of the RxTerms RESTful web API can be browsers, such as Internet Explorer or Firefox, or programs such as the Unix/Linux curl command, or user developed clients. For example, the Unix/Linux curl command could be used to get the RxTerms version:

curl http://rxnav.nlm.nih.gov/REST/RxTerms/version
(returns)
<?xml  version="1.0" encoding="UTF-8" standalone="yes"?><rxtermsdata><rxtermsVersion>RxTerms201011</rxtermsVersion></rxtermsdata>

Notice that the data returned from the RxTerms RESTful web API is in XML format. The curl command takes a URL as part of its command sequence. The string http://rxnav.nlm.nih.gov/REST/RxTerms/version is a RxTerms RESTful web API resource. The Resources section details the RxTerms RESTful web API resources available to clients.

Clients to the RxTerms RESTful web API provide resource names in the form of URIs to receive data about the resources. Currently, the RxTerms API RESTful web services return the data in XML form as the default. The API can also return the data in JSON or plain text format. Here is the curl command, modified from above, to return the RxTerms version in JSON format:

 curl -H "Accept:application/json" http://rxnav.nlm.nih.gov/REST/RxTerms/version
(returns)
{"rxtermsVersion":"RxTerms201106"}

Here is the curl command to return the RxNorm version in plain text format:

 curl -H "Accept:text/plain" http://rxnav.nlm.nih.gov/REST/RxTerms/version
(returns)
RxTerms201106

Resources

This section describes the resources of the RxTerms RESTful Web API. For users familiar with the SOAP-based RxTerms API, Table 1 lists the mapping between resources of the RxTerms RESTful web API and the SOAP-based RxTerms API functions. Note that for readability, the base URI has been omitted from the table, so for example the table contains "/version" instead of http://rxnav.nlm.nih.gov/REST/RxTerms/version. In addition, the text in italics indicates a user provided value. The notation {rxcui} indicates that an actual value of an RxCUI is needed.

Table 1 - Mapping of RxTerms API RESTful resources and SOAP-based web services

RESTful web service resource	SOAP-based web service function
/	none
/allconcepts	getAllConcepts
/rxcui/{rxcui}/allinfo	getAllRxTermInfo
/rxcui/{rxcui}/name	getRxTermDisplayName
/version	getRxTermsVersion

Resource "/"

This lists all the RxTerms resources.

Example

http://rxnav.nlm.nih.gov/REST/RxTerms/

(returns)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rxtermsdata>
  <resourceList>
    <resource>http://rxnav.nlm.nih.gov/REST/RxTerms/version</resource>
    <resource>http://rxnav.nlm.nih.gov/REST/RxTerms/allconcepts</resource>
    <resource>http://rxnav.nlm.nih.gov/REST/RxTerms/rxcui/{rxcui}/allinfo</resource>
    <resource>http://rxnav.nlm.nih.gov/REST/RxTerms/rxcui/{rxcui}/name</resource>
  </resourceList>
</rxtermsdata>

Resource "/allconcepts"

This resource returns all the RxTerms information.

Example

http://rxnav.nlm.nih.gov/REST/RxTerms/allconcepts

(returns)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rxtermsdata>
  <minConceptGroup>
    <minConcept>
      <fullName>0.09 ML pegaptanib 3.33 MG/ML Prefilled Syringe</fullName>
      <termType>SCD</termType>
      <rxcui>1011625</rxcui>
    </minConcept>
    <minConcept>
      <fullName>0.09 ML pegaptanib 3.33 MG/ML Prefilled Syringe [Macugen]</fullName>
      <termType>SBD</termType>
      <rxcui>1011626</rxcui>
    </minConcept>

   (many more ...)

  </minConceptGroup>
</rxtermsdata>

Resource "/rxcui/{rxcui}/allinfo"

This resource gets the RxTerms information for a specified RxNorm concept.

Example

http://rxnav.nlm.nih.gov/REST/RxTerms/rxcui/198440/allinfo

(returns)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rxtermsdata>
  <rxtermsProperties>
    <brandName/>
    <displayName>Acetaminophen (Oral-pill)</displayName>
    <synonym>APAP</synonym>
    <fullName>Acetaminophen 500 MG Oral Tablet</fullName>
    <fullGenericName>Acetaminophen 500 MG Oral Tablet</fullGenericName>
    <strength>500 mg</strength>
    <rxtermsDoseForm>Tabs</rxtermsDoseForm>
    <route>Oral-pill</route>
    <termType>SCD</termType>
    <rxcui>198440</rxcui>
    <genericRxcui>0</genericRxcui>
    <rxnormDoseForm>Oral Tablet</rxnormDoseForm>
    <suppress/>
  </rxtermsProperties>
</rxtermsdata>

Resource "/rxcui/{rxcui}/name"

Get the RxTerms display name for a specified RxNorm concept.

Example

http://rxnav.nlm.nih.gov/REST/RxTerms/rxcui/198440/name

(returns)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rxtermsdata>
  <displayGroup>
    <rxcui>198440</rxcui>
    <displayName>Acetaminophen (Oral-pill)</displayName>
  </displayGroup>
</rxtermsdata>

Resource "/version"

Get the RxTerms version

Example

http://rxnav.nlm.nih.gov/REST/RxTerms/version

(returns)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rxtermsdata>
  <rxtermsVersion>RxTerms201011</rxtermsVersion>
</rxtermsdata>

Comments? Feedback? Questions?
Contact: Contact us

U.S. National Library of Medicine, 8600 Rockville Pike, Bethesda, MD 20894
National Institutes of Health, Department of Health & Human Services
Copyright, Privacy, Accessibility