Summary
In this example, we are using PHP 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..
- Call the service and capture the response as a string using file_get_contents.
- Put the string into an Xml document using the SimpleXMLElement class.
- Select xml nodes that we are interested in from the Xml document using the
xpath function.
- Display the retrieved values on the 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:
$url ="http://dev.pedstep.org/PedStepTest/Rounding/GetRoundedDosesForMedication.aspx?".
"authToken=d4f3de8a-05d9-4c8c-9b8d-a205c58c523e&weightInKg=15.87&".
"ageInMonths=47&doseToRound=150&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, Capture the Response
Using the $url from the above section, we make the request to the service and capture the response as a string using file_get_contents.
// call the service using the $url and store response as a string
$responseString = file_get_contents($url);
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 .PHP, we will first need to convert the response string to a SimpleXMLElement object and then navigate it using the xpath function.
// put response string in a SimpleXMLElement object
$xml = new SimpleXMLElement($responseString);
// select the node with rounding recommendation
$RoundingRecNode = $xml->xpath("//RoundingRecommendation/Ranges/RoundingRange/Percentage");
// STEPSTools API puts the most recommended dose (highest score) as the first PossibleDose
// node, so define a path that selects this first node to get recommended dose
$recommendedDosePath = "//RoundingRecommendation/PossibleDoses/PossibleDosesList/PossibleDose[1]/";
// select nodes for formulation elements
$MedNameNode = $xml->xpath($recommendedDosePath."formulation/medname");
$IngredAmtNode = $xml->xpath($recommendedDosePath."formulation/ingred_amt");
$IngredUnitsNode = $xml->xpath($recommendedDosePath."formulation/ingred_units");
$LayAmtNode = $xml->xpath($recommendedDosePath."formulation/lay_amt");
$LayUnitsNode = $xml->xpath($recommendedDosePath."formulation/lay_units");
// select nodes for elements of the dose, score and message
$DoseAmtNode = $xml->xpath($recommendedDosePath."doseAdministrableAmount");
$DoseUnitsNode = $xml->xpath($recommendedDosePath."doseAdministrableUnits");
$ScoreNode = $xml->xpath($recommendedDosePath."Score");
$MessageNode = $xml->xpath($recommendedDosePath."Message");
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 the string that was used to call the service and the rounding recommendation
echo "<h4>Called</h4>".$url;
echo "<h4>Rounding Recommnedation</h4>".$RoundingRecNode[0];
// display the recommended formulation and dose, score for the dose, and message
echo "<h4>Recommended Dose</h4>";
echo "<b>Formulation:</b> ".
$DoseAmtNode[0]." ".$DoseUnitsNode[0]." of ".
$MedNameNode[0]." ".$IngredAmtNode[0]." ".$IngredUnitsNode[0]."/".
$LayAmtNode[0]." ".$LayUnitsNode[0]."<br>";
echo "<b>Score:</b> ".$ScoreNode[0]."<br>";
echo "<b>Message:</b> ".$MessageNode[0]."<br>";
echo "<h4>Full XML Response</h4>".$responseString;
You can download the full source code for the web page here.