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

Document created by JackCowardin Administrator on Oct 26, 2016Last modified by JackCowardin Administrator on Apr 4, 2017
Version 10Show Document
  • View in full screen mode

Introduction

GuideStar’s SOAP[1]-based web services, first implemented in 2008, are being deprecated in favor of more modern REST[2] APIs.

 

This document is intended to assist GuideStar Web Service customers in converting from these SOAP-based services to the newer and more efficient REST-ful API services.  

 

The idea of REST is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to communicate and pass data, simple HTTP is used to make calls between machines. While SOAP is a well-established and well-understood protocol for communicating data over the web, it can be complex to implement and ReST was developed to address and alleviate some of the difficulties associated with SOAP.  It may be useful to think of a SOAP web service call as an envelope for requesting data, and a ReST API call as a postcard. The SOAP call “wraps” the actual request in several layers of protocol, while the REST API call is more direct. Despite its simplicity, ReST is fully-featured. Anything you can do in Web Services can also be done with a RESTful architecture.

 

REST APIs are self-contained, and each request carries with it (transfers) all the information (state) that the server needs in order to complete it. REST API calls are simply URLs that also contain one or more parameters. The URL itself returns a defined data stream or structure that can be in the form of an XML document or a JavaScript Object Notation (JSON) document. The format of the returned data is specified by the user in the URL. GuideStar’s REST APIs favor the JSON format, but support both formats.  Authentication in APIs is included as part of the HTTP Header, as opposed to inclusion in the XML payload of a web service call.

 

SOAP web service calls, in contrast, are based on Extensible Markup Language (XML), and require that a text XML structure be created and posted to the Web Service Host as HTTP content.  The web service is exposed by means of a URL, but information must be passed to the web service in the XML message. This text XML message involves tags that bracket a “payload” containing query parameters or metadata that define the desired output of the web service call.

 

In many programming languages, SOAP requests must be constructed manually, and SOAP requires strict adherence to the structure that the web service expects. Some languages provide shortcuts, but the requirement is always there. Web Service interfaces are typically available by calling a URL that provides a WSDL (Web Services Description Language) document that tells a caller what "methods" (services) are available and how to correctly use the service. Authentication in web service calls is handled by inclusion of a user name and password in the XML data. Both web services and APIs employ HTTPS to protect usernames and passwords.

 

The result returned from the web server is an XML document (actually, a text ‘data stream’) that is also constructed of tags and returned data. The XML data is then parsed and applied to an output document or written to a database, for example.

 

The advantages of REST APIs over the older SOAP web services include:

  • Simpler calling convention – A URL with no need to construct an XML ‘payload’ for each request.
  • GuideStar provides an API “Sandbox”, where customers can develop their API calls at no charge. The Sandbox contains data that is not current, but is delivered in the same format that users will receive when they subscribe to corresponding production APIs.
  • APIs can be tested for correctness by entering them interactively in the address bar of a browser.
  • API Results can be requested in either JSON or XML format. GuideStar APIs support both, although we recommend JSON.
  • GuideStar’s APIs support the use of an API Key for authentication as well as standard username/password authentication. Customers can have multiple API keys so that they do not have to share their GuideStar credentials (username/password information) with contract developers.
  • ReST APIs are typically much faster than SOAP. They are also more easily parsed in code, particularly with JSON libraries available that speed development.
  • NPOs that use contract developers will appreciate that the code required to implement a ReST API call is significantly more simple than the code to implement an equivalent SOAP web service call.
  • ReST is also more aligned with the design philosophy of the Web.

 

More Information

A useful blog that compares SOAP to REST is available here, including an example that compares the work involved in using both:

http://blog.smartbear.com/apis/understanding-soap-and-rest-basics/

 

Conversion Code Examples

Web Service To API Conversion - Detail API Example

Web Service To API Conversion - CharityCheck PDF Example

Text Code Samples - Web Service to API Conversion

Example Data Classes for API Return Data

 

Results Comparison

Comparison:GuideStar Detail SOAP Web Service Results and REST Detail API Results

GuideStar Detail SOAP Web Service to REST Detail API Data Element Map 

CharityCheck REST API and getCCInfo() SOAP Response comparison 

GuideStarBasic web service to Search v1_1 API data map 

 

Related Information

How to Use the CharityCheck REST API to Check Revocation Status 


[1] SOAP is an acronym for Simple Object Access Protocol that uses XML and HTTP to allow disparate applications to exchange information across the web.

[2] REST is an acronym for Representational State Transfer, a protocol that is based on textual representations of web resources

[3] GuideStar APIs support only GET operations. They are read-only.

1 person found this helpful

Attachments

    Outcomes