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:
- Finding SOAP usage in your program
- Identifying analogous REST resources
- Choosing JSON or XML results
- 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 |
---|---|---|
InteractionAPI | Interaction APIs | Interaction REST API |
PrescribeAPIService | Prescribable APIs | Prescribable REST API |
RxClassDBService | RxClass APIs | RxClass REST API |
RxNormDBService | RxNorm APIs | RxNorm REST API |
RxTermsAPI | RxTerms APIs | RxTerms 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-1https://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 |
---|---|---|
InteractionAPI | Interaction member mapping (tab-separated text) | |
PrescribeAPIService | Prescribable member mapping (tab-separated text) | |
RxClassDBService | RxClass member mapping (tab-separated text) | |
RxNormDBService | RxNorm member mapping (tab-separated text) | /ndcstatus status capitalization differs from SOAP. |
RxTermsAPI | RxTerms 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:
- SOAP function name and number of arguments
- REST resource URL, with parameter substitions for SOAP parameter #1, #2, etc.
- Path to the REST result field that coincides with the SOAP return value
Any subsequent lines about the function have 2 fields:
- SOAP function name and arity + the path to a SOAP return-value field
- Corresponding path in the REST return value, relative to the REST field that corresponded to the SOAP item's containing object