REST and SOAP fundamentals

The decision between the two will be your first choice in designing a web service, so it is important to understand the pros and cons of the two. It is also important, in the sometimes heated debate between the two philosophies, to separate reality from rhetoric.

REST fundamentals

  • Everything in REST is considered as a resource.
  • Every resource is identified by a URI.
  • Uses uniform interfaces. Resources are handled using POST, GET, PUT, DELETE operations which are similar to Create, Read, Update and Delete (CRUD) operations.
  • Be stateless. Every request is an independent request. Each request from client to server must contain all the information necessary to understand the request.
  • Communications are done via representations. E.g., XML, JSON RESTful Web Services. A RESTful web services are based on HTTP methods and the concept of REST. A RESTful web service typically defines the base URI for the services; the supported MIME-types (XML, text, JSON, user-defined, …) and the set of operations (POST, GET, PUT, DELETE) which are supported.

SOAP fundamentals

  • WSDL defines the contract between client and service and is static by its nature.
  • SOAP builds an XML based protocol on top of HTTP or sometimes TCP/IP.
  • SOAP describes functions and types of data.
  • SOAP is a successor of XML-RPC and is very similar, but describes a standard way to communicate.
  • Several programming languages have native support for SOAP, you typically feed it a web service URL, and you can call its web service functions without the need for specific code.
  • Binary data that is sent must be encoded first into a format such as base64 encoded.
  • Has several protocols and technologies relating to it: WSDL, XSD, SOAP, WS-Addressing.

SOAP vs REST?

One of the major benefits of SOAP is that you have a WSDL service description. You can pretty much discover the service automatically and generate a useable client proxy from that service description (generate the service calls, the necessary data types for the methods and so forth). Note that with version 2.0, WSDL supports all HTTP verbs and can be used to document RESTful services as well, but there is a less verbose alternative in WADL (Web Application Description Language) for that purpose.

With RESTful services, message security is provided by the transport protocol (HTTPS) and is point-to-point only. It doesn’t have a standard messaging system and expects clients to deal with communication failures by retrying. SOAP has successful/retry logic built in and provides end-to-end reliability even through SOAP intermediaries.

One of the major benefits of RESTful API is that it is flexible for data representation, for example, you could serialize your data in either XML or JSON format. RESTful APIs are cleaner or easier to understand because they add an element of using standardized URIs and gives importance to HTTP verb used (i.e., GET, POST, PUT and DELETE).

RESTful services are also lightweight, that is they don’t have a lot of extra XML markup. To invoke RESTful API all you need is a browser or HTTP stack and pretty much every device or machine connected to a network has that.