Introduction to Web APIs ~ REST vs SOAP

When interacting with web services, generally the choice of which method to use will be made for you. The majority of services operate in either REST or SOAP, not both (Amazon is a notable exception to this rule). When given the choice, however, there are several points to consider:

• Overhead — REST requests are relatively slim. SOAP requests, on the other hand, contain a lot of additional information, which can really add up.

• Transparency — With REST requests (even when completed over HTTPS), all request information is sent in the clear; with SOAP only the end point (URL) is visible. This may sound like a clear-cut win for SOAP, but not quite. When requests go in the clear, they can easily be monitored by the relevant IT departments and screened by firewalls. REST requests can also be easily cached (when this is marked as allowable by the server) by existing infrastructure, reducing server load and bandwidth costs.

• Ease of use — Many developers have indicated a preference to develop for REST servers, because the requests can be quickly generated without all the extra encapsulation required by SOAP. Amazon, for example (offering both REST and SOAP interfaces), has 85 percent of its requests occur over REST.

• Service definition — SOAP services are defined by Web Services Description Language (WSDL) files, which contain all the information required to make a request. In fact, generic SOAP clients are available that will allow you to make any request provided by a service given nothing but the address of the WSDL file. There is no equivalent for REST services.

• Encapsulation — SOAP requests are encapsulated within an XML envelope. The body of the request itself is then again encapsulated within a body element. The addition of namespacing within the document goes further to clearly define exactly what each element is describing. There are several excellent tools out there to assist document creation, which can take the tedium out of creating these longer requests.

Overall, there is no clear winner (if there was, I wouldn't need to introduce both). The choice will depend on the particular application and the tools available to build it. Generally speaking, when given the choice, I prefer to use SOAP in my web service communications. I feel that the service definition and encapsulation provided by SOAP outweighs the additional overhead and lack of protocol-level transparency.