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.
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.
A useful blog that compares SOAP to REST is available here, including an example that compares the work involved in using both:
Conversion Code Examples