Practical Web Service Application Conversion to REST API Example

Document created by JackCowardin Administrator on Nov 18, 2016Last modified by JackCowardin Administrator on Dec 2, 2016
Version 3Show Document
  • View in full screen mode

GuideStar partners with many other philanthropic organizations and provides data to them that they use in their own websites and applications.

 

A typical use of GuideStar's (SOAP-based) web services might involve an initial call to the GuideStarBasic web service to search for charities or foundations. Once a charity, for example, is selected, the GuideStarDetail SOAP service would be called to return more detailed information about the selected charity. The conversion of this web application to use GuideStar REST APIs would involve the use of the Search API and the Detail or Profile API.

 

One GuideStar partner provides a search capability on their web site like this one shown below:

 

A search form provided by a GuideStar partner

 

Assume that we're interested in donating to a non-profit in our town of Cleveland Ohio. We enter the search term "Cleveland". 

 

The partner website uses the GuideStarBasic web service to retrieve a list of non-profit organizations (NPOs) with the term Cleveland in their name. The search data is returned by the GuideStar web service, and formatted by the host web site for the user to select an NPO for further examination.

 

View actual result of the web service call here:

GuideStarBasic Web Service Results 

 

 

 

 

Search Results from the GuideStarBasic web serviceThe user then selects "Cleveland Museum of Art" and clicks the button labeled "Research".

 

 

 

 

The web site then invokes the GuideStarDetail web service and receives detailed information about the Cleveland Museum of Art. 

 

See the data returned by the GuideStarDetail web service call here:

GuideStarDetail Legacy Web Service .

 

 

 

 

 

 

 

The more detailed data is formatted by the partner web site in a report that the user can examine to be confident in making their donation.

 

This web application can be converted to use the GuideStar REST APIs by replacing the code used to invoke the web services and calling the URLs at

data.guidestar.org/v1_1/Search?q=cleveland

and

data.guidestar.org/v1/detail/34-0714336.

 

The returned results will differ slightly in format, but the data will be consistent with the return from the web service calls. The application will need to be modified slightly to handle any difference between the SOAP and REST data.

 

See a direct, side-by-side comparison of the returned data here:

 

An advantage of the REST API is that the return data can be in JSON (JavaScript Object Notation) format, and thus easily "deserialized" (processed) into software "objects" in many languages that make dealing with the data more direct than with with XML parsing.

 

GuideStar provides C# object classes that will accept deserialized JSON API return data to facilitate programmatic access to the returned data. Find those classes here:

<link to example classes>

Attachments

    Outcomes