Building Applications to Use the RxNorm (SOAP) APIThis page describes how to build applications to use the RxNorm SOAP API. The same steps can be used for the Prescribable, RxTerms and NDF-RT APIs by substituting the appropriate service names contained in the WSDL files for those APIs.
We provide documentation for coding Java and .Net applications. Documentation for building applications in other programming languages (e.g. Perl) may be added at a later time.
Building a Java Application to use the RxNorm APIThe RxNorm API provides developers with functions for retrieving RxNorm data from the most current RxNorm data set. Building applications to use the RxNorm API require initial setup of the development environment and developing code. Each of these is described in detail in this chapter.
Java Development Environment SetupSetup of a Java developer's environment involves the following steps. All steps must be completed before application code can be compiled and built to execute requests with the RxNorm API.
- Obtain a Simple Object Access Protocol (SOAP) 1.2 compatible engine for web service message routing.
- Download the WSDL for the RxNorm API web service.
- Generate the client side stubs using Axis's WSDL2Java utility for the WSDL (for applications written in Java).
1. Obtaining a SOAP 1.2 EngineDevelopers will require a Simple Object Access Protocol (SOAP) 1.2 compatible engine to route the web service messages to/from the RxNorm API. The client programs shown in this guide have been tested with Apache Axis Version 1.4 Follow the link to their website and download and install the version onto your development machine. The location of this download will be referred to as <AXIS_DIR> in this guide.
2. Downloading the RxNorm WSDLThe RxNorm WSDL may be downloaded from the RxNav web site. Right-click on the RxNorm Service WSDL and save the WSDL file to your development machine. The path to this file will be hereafter referred to as <RXNORM_WSDL_LOCATION>.
3. Generating Client Stubs for JavaApache Axis is delivered with a utility to generate Java classes from a WSDL. Using WSDL2Java generates client stubs that enable communication with a defined web service.
prompt> java -classpath <CLASSPATH> org.apache.axis.wsdl.WSDL2Java \ <RXNORM_WSDL_LOCATION>The call to the utility places generated Java class files in the directory where the utility is run. The <CLASSPATH> must include the following jar files generally found in the lib directory of the Axis installation:
axis.jar wsdl4j-1.5.1.jar commons-logging-1.0.4.jar commons-discovery-0.2.jar jaxrpc.jar saaj.jar activation.jar mail.jarOther SOAP engines use different utilities to generate the client stubs. Refer to your specific SOAP engine documentation for instructions on building the client stubs using the downloaded WSDL.
Coding Java Applications to use the RxNorm APIThe basic paradigm for obtaining RxNorm data from the RxNorm API web service is as follows:
- Establish a connection to the RxNorm API web service.
- Obtain the data from the RxNorm API web service.
Java Code: Establishing a Connection to the RxNorm API Web ServiceThe RxNorm API web service is an Axis web service running at the NLM on the RxNav production machine. The web service endpoint URI is
http://mor.nlm.nih.gov/axis/services/RxNormDBServiceThe classes generated during WSDL2Java execution must be imported into your application. For Java applications, include these import statements:
import java.net.URL; import BeanService.*; import gov.nih.nlm.rxnav.axis.services.RxNormDBService.*;The following code snippet shows how to establish a connection to the RxNorm API web service.
String rxhost = "http://mor.nlm.nih.gov"; String rxURI = rxhost + "/axis/services/RxNormDBService"; // Locate the RxNorm API web service URL rxURL = new URL(rxURI); DBManagerService rxnormService = new DBManagerServiceLocator(); DBManager dbmanager = rxnormService.getRxNormDBService(rxURL);
Java Code: Obtaining RxNorm DataThe RxNorm API web service provides access to current RxNorm data through its calls defined in the WSDL. The code snippet below searches for a concept unique identifier (RxCUI) using exact matching of an input string. Each operation made available in the RxNorm API web service is described in detail in the RxNorm API design document.
// Get the concept unique identifier for a string String  rxcuis = dbmanager.findRxcuiByString("aspirin"); // print results for (int j = 0; j < rxcuis.length; j++) System.out.println("RXCUI = " + rxcuis[j]); if (rxcuis.length == 0) System.out.println("No concept found");
Compiling the Java ApplicationWhen compiling the application using the RxNorm API, the CLASSPATH must include the directory into which the compiled stubs were put and the following jar files which are generally found in the lib directory of the Axis installation:
axis.jar wsdl4j-1.5.1.jar commons-logging-1.0.4.jar commons-discovery-0.2.jar jaxrpc.jar saaj.jar activation.jar mail.jar
Building a .Net Application to use the RxNorm API
.Net Development Environment and Project SetupSetup of a .Net developer's environment involves the following steps:
- Install a current version of Microsoft Visual Studio .Net, selecting at least these options: VB, C#, and Web development. This tutorial mainly assumes VS 2010, but 2008 is known to work with minor differences.
- Start up Visual Studio. If it asks for default settings, choose C# or VB, depending on your preference. In this tutorial, we use C#.
- From the Visual Studio menu, choose File -> New Project
In the Left pane, choose Visual C# -> Windows
In the Right Pane, choose either Console Application (for a command-line-driven application) or Windows Forms Application (for a GUI-driven application)
In the "Name:" box, enter a name for your project: RxNormClient or RxNorm_GUI_Client (or any project name you want)
A new C# file skeleton named Program.cs that contains an empty Main() method in the Program class will be generated.
- Do not close Visual Studio and do not close the project or the current program file. You will need to return here later to complete the project setup.
Downloading the RxNorm WSDL and Generating a Client Stub for .NetIn the steps below,
- [your_home_dir] refers to where the RxNormClient "Program.cs" file was just generated. Example on Windows XP with VS 2010:
C:\Documents and Settings\[your_username]\\My Documents\Visual Studio 2010\Projects\RxNormClient\RxNormClient
- [your_wsdl_dir] is where the latest version of wsdl.exe is on your machine. Typical examples:
C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\NETFX 4.0 Tools
- [your_csc_dir] is where the latest version of csc.exe is on your machine. Examples:
cd [your_source_dir] "[your_wsdl_dir]\wsdl.exe" /l:CS /protocol:SOAP http://rxnav.nlm.nih.gov/RxNormDBService.xmlThe following message should be displayed:
Writing file '[your_source_dir]\DBManagerService.cs'Your client stub is in the .cs file that was just created (DBManagerService.cs in this example)
Putting the pieces together into a .Net project
- You can now either...
- Add your client stub source file to your project in Visual Studio
- In the Solution Explorer pane, right-click the project name and choose Add ->
(The beauty of this option is that it allows you to step into the stub source code in Debug mode.)
- In the Solution Explorer pane, right-click the project name and choose Add -> Existing Item
- Compile the stub into a DLL, by first executing the command line:
"[your_csc_dir]\csc.exe" /t:library /r:System.Web.Services.dll /r:System.Xml.dll DBManagerService.csthen adding the DLL as a Reference to your project:
- Right-click the project name in the Solution Explorer pane
- Choose Add Reference... then select the Browse tab.
- Add your client stub source file to your project in Visual Studio
- Finally, your project needs a reference to the .Net Web Services namespace before it will compile:
- Right-click the project name in the Solution Explorer pane.
- Choose Add Reference... then select the .Net tab.
- Select System.Web.Services and click OK.
- You are now ready to code your class's Main() method in any way you wish.