Summary
In this example, we are using C#, ASP.NET 3.5, and Visual Studio 2008 Professional to build a simple web page which calls the GetRoundedDosesForMedication method of the STEPSTools Rounding service. These are the steps we will take:
- Build a string that contains a simple HTTP GET call to the service. This will be a fully-qualified url of the method of the service inluding the method's required parameters and values as a querystring..
- Use the HttpWebRequest and HttpWebResponse classes to hit the url address and capture the response from the service.
- Since the response from the service will be an xml document, we use the XPathNavigator Class to navigate the document to find what we need.
- Display the results on a simple ASP.NET web page.
Let's break down each step.
Build a String for the Request
Before proceeding, if you haven't done so already, you should review the documentation for this method of the web service. In that documentation, use the Practice Tool at the bottom and notice the url addresses that are used to call the service. This will give you an idea of what your url string should look like. We start by building the string:
// build the call to the service as a string
StringBuilder sbRequestString = new StringBuilder();
sbRequestString.Append("http://dev.pedstep.org/Rounding/GetRoundedDosesForMedication.aspx?");
sbRequestString.Append("authToken=a56887bd-d7cb-49e0-a308-d1edef18934a&weightInKg=15.87&");
sbRequestString.Append("ageInMonths=47&doseToRound=250.4&doseUnits=mg&medicationString=amoxicillin");
Please, note: In this example, the authToken is hard-coded to make the example fairly simple. The STEPSTools team recommends that you NOT do this in your actual production code as authTokens can change. Rather, you should store your authToken in a mutable data store (like a flat file or data table) and call the GetAuthToken method of the service whenever an authToken gets rejected by the service.
Call the Service and Capture the Response
Using the sbRequestString from the above section, we make the request to the service and capture the response as a stream. We then read the stream into a string using the StreamReader class.
// make the call using the string and capture in a stream
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(sbRequestString.ToString());
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
Stream stream = response.GetResponseStream();
// read the stream into a string
Encoding encode = System.Text.Encoding.GetEncoding("utf-8");
string responseStreamAsString = new StreamReader(stream, encode).ReadToEnd();
Navigate the XML Response
You could, at this point, use simple string parsing to find what you need in the response. However, the responses from the STEPSTools API can, in some cases, be fairly complex, so we recommend using XPath for it's superior ability to leverage the XML structure of the responses from the API. To do this in .NET, we will first need to convert the response string to an XmlDocument object and then navigate it using the previously mentioned XPathNavigator Class.
// create an XmlDocument and load the string into it
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.LoadXml(responseStreamAsString);
// create an XmlNavigator for the document and capture values using XPath
XPathNavigator navigator = xmlDoc.CreateNavigator();
string roundingPercentage =
navigator.Evaluate("string(//RoundingRecommendation/Ranges/RoundingRange/Percentage)").ToString();
// the GetRoundedDosesForMedication puts the most recommended dose (highest score) as the first PossibleDose node,
// so we use XPath to select this node to get the most recommended dose
string recDosePath = "//RoundingRecommendation/PossibleDoses/PossibleDosesList/PossibleDose[1]/";
// use recDosePath in XPath queries to capture additional data elements about the dose
string formulationString = navigator.Evaluate("string(" + recDosePath + "formulation/medname)").ToString() + " "
+ navigator.Evaluate("string(" + recDosePath + "formulation/ingred_amt)").ToString() + " "
+ navigator.Evaluate("string(" + recDosePath + "formulation/ingred_units)").ToString() + "/"
+ navigator.Evaluate("string(" + recDosePath + "formulation/lay_amt)").ToString() + " "
+ navigator.Evaluate("string(" + recDosePath + "formulation/lay_units)").ToString();
string doseString = navigator.Evaluate("string(" + recDosePath + "doseAdministrableAmount)").ToString() + " "
+ navigator.Evaluate("string(" + recDosePath + "doseAdministrableUnits)").ToString();
string score = navigator.Evaluate("string(" + recDosePath + "Score)").ToString();
string message = navigator.Evaluate("string(" + recDosePath + "Message)").ToString();
Display Results
From here, there are obviously a multitude of options for how you might want to display the data. In this example, to keep it simple, I'm simple going to drop the captured values in a label on the web page:
// display results on the page
LabelRoundingPercentage.Text = "<h3>Rounding Rec</h3>" + roundingPercentage ;
LabelRecommendedDose.Text = "<h3>Recommended Dose</h3>"
+ "<b>Formulation</b>: " + formulationString + "<br>"
+ "<b>Dose</b>: " + doseString + "<br>"
+ "<b>Score</b>: " + score + "<br>"
+ "<b>Message</b>: " + message;
LabelResponse.Text = "<h3>Full Xml Respons</h3>" + HttpUtility.HtmlEncode(responseStreamAsString);
You can download the full source code for the web page here.