Web Service To API Conversion - Detail API Example

Document created by JackCowardin Administrator on Oct 26, 2016Last modified by JackCowardin Administrator on Dec 2, 2016
Version 13Show Document
  • View in full screen mode

A Practical Example

As an example, we will use one of the GuideStar Web Services that are exposed with the URL

https://gsservices.guidestar.org/GuideStar_SearchService/SearchService.asmx.

 

These include

 

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:

  Detail Web Svc query.PNG

The entire SOAP (version 1.2) request looks like this:

 

SOAP Envelope.PNG

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

web svc code.PNG


For comparison, we will describe the implementation of the GuideStar Detail API that can be accessed with this URL:

 

https://data.guidestar.org/v1/detail/7394706

 

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:

  1. create a web request object,
  2. add the user ID and password in the HTTP header as “credentials”,
  3. 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.

 

api code.PNG

 

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.

 

Text Code Samples - Web Service to API Conversion

 

Results Comparison

Comparison:GuideStar Detail Web Service Results and Detail API Results

 

Back

Converting from GuideStar Web Services (SOAP) to APIs (REST).

Attachments

    Outcomes