A Practical Example
As an example, we will use one of the GuideStar Web Services that are exposed with the URL
- This service was superseded by an updated Web Service
We will use the GuideStarDetail web service and compare its implementation and results to the GuideStar Detail API. The keyword “Cleveland Clinic” will be the search term. The GuideStar Detail ReST API takes as a parameter an Organization ID for a specific organization, so the Organization ID for the Cleveland Clinic, 7394706, will be used for the Detail API call. This allows a more direct comparison of the return values of the two methods.
The XML query for the call to the GuideStar Detail web service needs to look like this:
The entire SOAP (version 1.2) request looks like this:
In terms of programming this web service call, many languages offer libraries for this type of communication. In Microsoft .NET, you set up a web reference to https://gsservices.guidestar.org/GuideStar_SearchService/SearchService.asmx.
The web reference is a shortcut that handles much of the overhead of the web service call. Some sample C# code to call the web service is below. The basic call requires only about 5 lines of code (in bold). However, another 11 lines of code are needed to construct the xml query, and this discounts the overhead associated with the web service reference :
Text of code samples is here: Text Code Samples - Web Service to API Conversion
For comparison, we will describe the implementation of the GuideStar Detail API that can be accessed with this URL:
Note that this isn't the request body -- it's just a URL. This URL is sent to the server using a simple GET request, and the HTTP reply is the raw result data -- not embedded inside anything, just the data you need in a way you can directly use.
The actual implementation in C# code takes 3 steps:
- create a web request object,
- add the user ID and password in the HTTP header as “credentials”,
- execute the request and display the results.
This code takes 5 lines (okay, 6 with the ReadKey pause...), and does not require the creation of an xml input query or a WebServiceReference as the web service call does.
If the requested data is to be delivered from the API in JSON format, simply omit the ".xml" at the end of the URL of the web request. It should be clear from these examples that the overhead associated with the SOAP (Web Service) protocol is significantly greater than that of the ReST API protocol. In terms of validation of the results, the URL in the web request above can be entered directly in the address bar of any browser and the formatted results will be displayed there. These results can be compared with the results of the coded solution for validation.