RXNAV

News Archive

API Updates

RxNav SOAP to REST Migration Guide

As API users gravitate to RxNav's REST APIs for performance and convenience, RxNav's SOAP service had fallen behind feature parity. It was terminated in January 2020. SOAP API users are encouraged to switch to the REST APIs.

This page offers general orientation and reference material for a programmer who is about to revise programs that use RxNav's SOAP APIs, to use the REST APIs instead:

  1. Finding SOAP usage in your program
  2. Identifying analogous REST resources
  3. Choosing JSON or XML results
  4. Harvesting information from REST results

SOAP and REST are standard techniques used with a variety of programming languages and a plethora of tools. Therefore, we cannot offer step-by-step programming advice.

Finding SOAP usage in your program

To find out whether your program uses the RxNav SOAP APIs, you may examine the program's source code. Searching the source code for the following phrases should lead to clues:

  • http://mor.nlm.nih.gov/axis/services/
  • https://mor.nlm.nih.gov/axis/services/

After "/services/" comes the name of the SOAP API, cumulatively one of these:

  • https://mor.nlm.nih.gov/axis/services/InteractionAPI
  • https://mor.nlm.nih.gov/axis/services/PrescribeAPIService
  • https://mor.nlm.nih.gov/axis/services/RxClassDBService
  • https://mor.nlm.nih.gov/axis/services/RxNormDBService
  • https://mor.nlm.nih.gov/axis/services/RxTermsAPI

Having obtained a handle to a SOAP API by means of one of the above URLs, a program may invoke the functions of that API. Those invocations need to be changed to use REST. A first step is to find the REST resource analogous to each SOAP function that the program invokes.


Identifying analogous REST resources

Each RxNav SOAP API corresponds to a REST API with analogous resources. See the pertinent RxNav documentation pages, linked from the table below. You can even try live examples of the REST resources:

SOAP API SOAP-to-REST
function correspondence
REST API Documentation
InteractionAPIInteraction APIsInteraction REST API
PrescribeAPIServicePrescribable APIsPrescribable REST API
RxClassDBServiceRxClass APIsRxClass REST API
RxNormDBServiceRxNorm APIsRxNorm REST API
RxTermsAPIRxTerms APIsRxTerms REST API

Choosing JSON or XML results

Each RxNav REST API resource can be retrieved as either XML or JSON. The information is the same. You may choose whichever format is more convenient. Insert the extension (.xml or .json) in the REST URL before the query parameters. For example:

https://rxnav.nlm.nih.gov/REST/rxcui.xml?idtype=NDC&id=11523-7020-1
https://rxnav.nlm.nih.gov/REST/rxcui.json?idtype=NDC&id=11523-7020-1

Harvesting information from REST results

Every member of an object returned by a SOAP API function corresponds to a field of the XML or JSON result from the analogous REST resource.

If you are converting a few distinct SOAP calls to REST, the easiest way to learn the corresponding REST call and result format is to check the REST API documentation (linked above).

  • Samples are provided for each REST resource. Because it's REST, you may simply follow the sample URL in your browser to see the results.
  • Each REST API page links to an XML schema. You may read the schema to learn about the result data. RxNav's JSON also mirrors the XML format.

We are also providing data files of the SOAP-to-REST correspondence. Each file matches one API's SOAP functions and result objects to REST. The files may be especially helpful if you are contemplating an automated adaptation of your program to use REST.

SOAP API SOAP-to-REST field map file Notes
InteractionAPIInteraction member mapping (tab-separated text) 
PrescribeAPIServicePrescribable member mapping (tab-separated text) 
RxClassDBServiceRxClass member mapping (tab-separated text) 
RxNormDBServiceRxNorm member mapping (tab-separated text)/ndcstatus status capitalization differs from SOAP.
RxTermsAPIRxTerms member mapping (tab-separated text) 

Using the field-map files

There is one SOAP-to-REST field mapping file per SOAP interface. The file contains one line per result field per SOAP function.

The first line about a function has 3 fields:

  1. SOAP function name and number of arguments
  2. REST resource URL, with parameter substitions for SOAP parameter #1, #2, etc.
  3. Path to the REST result field that coincides with the SOAP return value

Any subsequent lines about the function have 2 fields:

  1. SOAP function name and arity + the path to a SOAP return-value field
  2. Corresponding path in the REST return value, relative to the REST field that corresponded to the SOAP item's containing object