Representational state transfer (REST) and Simple

Question

Can somebody explain what is REST and what is SOAP in plain english? And how Web Services work?

Answer 1

This is the simplest explanation you will ever find.

This article takes a husband to wife narrative, where the husband explains to his wife about REST, in pure layman terms. Must read!

how-i-explained-rest-to-my-wife (original link)
how-i-explained-rest-to-my-wife (2013-07-19 working link)

Answer 2

Both methods are used by many of the large players. It's a matter of preference. My preference is REST because it's simpler to use and understand.

Simple Object Access Protocol (SOAP):

• SOAP builds an XML 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 of 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, XSDs, SOAP, WS-Addressing

Representational state transfer (REST):

• REST need not be over HTTP but most of my points below will have an HTTP bias.
• REST is very lightweight, it says wait a minute, we don't need all of this complexity that SOAP created.
• Typically uses normal HTTP methods instead of a big XML format describing everything. For example to obtain a resource you use HTTP GET, to put a resource on the server you use HTTP PUT. To delete a resource on the server you use HTTP DELETE.
• REST is a very simple in that it uses HTTP GET, POST and PUT methods to update resources on the server.
• REST typically is best used with Resource Oriented Architecture (ROA). In this mode of thinking everything is a resource, and you would operate on these resources.
• As long as your programming language has an HTTP library, and most do, you can consume a REST HTTP protocol very easily.
• Binary data or binary resources can simply be delivered upon their request.

There are endless debates on REST vs SOAP on google.

My favorite is this one. Update 27 Nov 2013: Paul Prescod's site appears to have gone offline and this article is no longer available, copies though can be found on the Wayback Machine or as a PDF at CiteSeerX.

Answer 3

Simple explanation about SOAP and REST

SOAP - "Simple Object Access Protocol"

SOAP is a method of transferring messages, or small amounts of information, over the Internet. SOAP messages are formatted in XML and are typically sent using HTTP (hypertext transfer protocol).

---

Rest - Representational state transfer

Rest is a simple way of sending and receiving data between client and server and it doesn't have very many standards defined. You can send and receive data as JSON, XML or even plain text. It's light weighted compared to SOAP.

---

Answer 4

I like Brian R. Bondy's answer. I just wanted to add that Wikipedia provides a clear description of REST. The article distinguishes it from SOAP.

REST is an exchange of state information, done as simply as possible.

SOAP is a message protocol that uses XML.

One of the main reasons that many people have moved from SOAP to REST is that the WS-* (called WS splat) standards associated with SOAP based web services are EXTREMELY complicated. See wikipedia for a list of the specifications. Each of these specifications is very complicated.

EDIT: for some reason the links are not displaying correctly. REST = http://en.wikipedia.org/wiki/REST

WS-* = http://en.wikipedia.org/wiki/WS-*

Answer 5

Both SOAP webservices and REST webservices can use the HTTP protocol and other protocols as well (just to mention SOAP can be the underlying protocol of REST). I will talk only about the HTTP protocol related SOAP and REST, because this is the most frequent usage of them.

SOAP

SOAP ("simple" object access protocol) is a protocol (and a W3C standard). It defines how to create, send and process SOAP messages.

• SOAP messages are XML documents with a specific structure: they contain an envelope which contains the header and the body section. The body contains the actual data - we want to send - in an XML format. There are two encoding styles, but we usually choose literal, which means that our application or its SOAP driver does the XML serialization and unserialization of the data.

• SOAP messages travel as HTTP messages with SOAP+XML MIME subtype. These HTTP messages can be multipart, so optionally we can attach files to SOAP messages.

• Obviously we use a client-server architecture, so the SOAP clients send requests to the SOAP webserices and the services send back responses to the clients. Most of the webservices use a WSDL file to describe the service. The WSDL file contains the XML Schema (XSD hereafter) of the data we want to send and the WSDL binding which defines how the webservice is bound to the HTTP protocol. There are two binding styles: RPC and document. By the RPC style binding the SOAP body contains the representation of an operation call with the parameters (HTTP requests) or the return values (HTTP response). The parameters and return values are validated against the XSD. By the document style binding the SOAP body contains an XML document which is validated against the XSD. I think the document binding style is better suited to event based systems, but I never used that binding style. The RPC binding style is more prevalent, so most people use SOAP for XML/RPC purposes by distributed applications. The webservices usually find each other by asking an UDDI server. UDDI servers are registries which store the location of the webservices.

SOAP RPC

So the - in my opinion - most prevalent SOAP webservice uses RPC binding style and literal encoding style and it has the following properties:

• It maps URLs to operations.
• It sends messages with SOAP+XML MIME subtype.
• It can have a server side session store, there are no constraints about that.
• The SOAP client drivers use the WSDL file of the service to convert the RPC operations into methods. The client side application communicates with the SOAP webservice by calling these methods. So most of the SOAP clients break by interface changes (resulting method names and/or parameter changes).
• It is possible to write SOAP clients which won't break by interface changes using RDF and find operations by semantics, but semantic webservice are very rare and they don't necessarily have a non breaking client (I guess).

REST

REST (representational state transfer) is an architecture style which is described in the dissertation of Roy Fielding. It does not concern about protocols like SOAP does. It starts with a null architecture style having no constraints and defines the constraints of the REST architecture one by one. People use the term RESTful for webservices which fulfill all of the REST constraints, but according to Roy Fielding, there are no such things as REST levels. When a webservice does not meet with every single REST constraint, then it is not a REST webservice.

REST constraints

• Client - server architecture - I think this part is familiar to everyone. The REST clients communicate with the REST webservices, the webservices maintain the common data - resource state hereafter - and serve it to the clients.
• Stateless - The "state transfer" part of the abbreviation: REST. The clients maintain the client state (session/application state), so the services must not have a session storage. The clients transfer the relevant part of the client state by every request to the services which respond with the relevant part of the resource state (maintained by them). So requests don't have context, they always contain the necessary information to process them. For example by HTTP basic auth the username and the password is stored by the client, and it sends them with every request, so authentication happens by every request. This is very different from regular webapplications where authentication happens only by login. We can use any client side data storage mechanism like in-memory(javascript), cookies, localStorage, and so on... to persist some parts of the client state if we want. The reason of the statelessness constraint, that the server scales well - even by very high load (millions of users) - when it does not have to maintain the session of every single client.
• Cache - The response must contain information about it can be cached by the client or not. This improves scalability further.

• Uniform interface

  • Identification of resources - REST resource is the same as RDF resource. According to Fielding if you can name something, then it can be a resource, for example: "the current local weather" can be a resource, or "your mobile phone" can be a resource, or "a specific web document" can be a resource. To identify a resource you can use resource identifiers: URLs and URNs (for example ISBN number by books). A single identifier should belong only to a specific resource, but a single resource can have many identifiers, which we frequently exploit for example by pagination with URLs like https://example.com/api/v1/users?offset=50&count=25. URLs have some specifications, for example URLs with the same pathes but different queries are not identical, or the path part should contain the hierarhical data of the URL and the query part should contain the non-hierarchical data. These are the basics of how to create URLs by REST. Btw. the URL structure does matter only for the service developers, a real REST client does not concern with it. Another frequently asked question is API versioning, which is an easy one, because according to Fielding the only constant thing by resource is semantics. If the semantics change, then you can add a new version number. You can use classical 3 number versioning and add only the major number to the URLs (https://example.com/api/v1/). So by backward compatible changes nothing happens, by non-backward compatible changes you will have a non-backward compatible semantics with a new API root https://example.com/api/v2/. So the old clients won't break, because they can use the https://example.com/api/v1/ with the old semantics.
  • Manipulation of resources through representations - You can manipulate the data related to resources (resource state) by sending the intended representation of the resources - along with the HTTP method and the resource identifier - to the REST service. For example if you want to rename a user after marriage, you can send a PATCH https://example.com/api/v1/users/1 {name: "Mrs Smith"} request where the {name: "Mrs Smith"} is a JSON representation of the intended resource state, in other words: the new name. This happens vica-versa, the service sends representations of resources to the clients in order to change their states. For example if we want to read the new name, we can send a GET https://example.com/api/v1/users/1?fields="name" retrieval request, which results in a 200 ok, {name: "Mrs Smith"} response. So we can use this representation to change the client state, for example we can display a "Welcome to our page Mrs Smith!" message. A resource can have many representations depending on the resource identifier (URL) or the accept header we sent with the request. For example we can send an image of Mrs Smith (probably not nude) if image/jpeg is requested.
  • Self-descriptive messages - Messages must contain information about how to process them. For example URI and HTTP method, content-type header, cache headers, RDF which describes the meaning of the data, etc... It is important to use standard methods. It is important to know the specification of the HTTP methods. For example GET means retrieving information identified by the request URL, DELETE means asking the server to delete the resource identified by the given URL, and so on... HTTP status codes have a specification as well, for example 200 means success, 201 means the a new resource has been created, 404 means that the requested resource was not found on the server, etc... Using existing standards is an important part of REST.

  • Hypermedia as the engine of application state (HATEOAS hereafter) - Hypermedia is a media type which can contain hyperlinks. By the web we follow links - described by a hypermedia format (usually HTML) - to achieve a goal, instead of typing the URLs into the addres bar. REST follows the same concept, the representations sent by the service can contain hyperlinks. We use these hyperlinks to send requests to the service. With the response we get data (and probably more links) which we can use to build the new client state, and so on... So that's why hypermedia is the engine of application state (client state). You probably wonder how do clients recognize and follow the hyperlinks? By humans it is pretty simple, we read the title of the link, maybe fill input fields, and after that just a single click. By machines we have to add semantics to the links with RDF (by JSON-LD with Hydra) or with hypermedia specific solutions (for example IANA link relations and vendor specific MIME types by HAL+JSON). There are many machine readable XML and JSON hypermedia formats, just a short list of them:

    • XHTML
    • ATOM+XML
    • RDF+XML
    • HAL+XML
    • HAL+JSON
    • JSON-LD
    • RDF+JSON
    • Siren
    • Collection+JSON

    Sometimes it is hard to choose...

• Layered system - We can use multiple layers between the clients and the services. None of them should know about all of these additonal layers, just of layer right next to it. These layers can improve scalability by applying caches and load balancing or they can enforce security policies.
• Code on demand - We can send back code which extends the functionality of the client, for example javascript code to a browser. This is the only optional constraint of REST.

REST webservice - SOAP RPC webservice differences

So a REST webservice is very different from a SOAP webservice (with RPC binding style and literal encoding style)

• It defines an uniform interface (intead of a protocol).
• It maps URLs to resources (and not operations).
• It sends messages with any MIME types (instead of just SOAP+XML).
• It has a stateless communication, and so it cannot have a server side session storage. (SOAP has no constraint about this)
• It serves hypermedia and the clients use links contained by that hypermedia to request the service. (SOAP RPC uses operation bindings described in the WSDL file)
• It does not break by URL changes only by semantics changes. (SOAP RPC clients without using RDF semantics break by WSDL file changes.)
• It scales better than a SOAP webservice because of its stateless behavior.

and so on...

A SOAP RPC webservice does not meet all of the REST constraints:

• client-server architecture - always
• stateless - possible
• cache - possible
• uniform interface - never
• layered system - never
• code on demand (optional) - possible

Answer 6

Well I'll begin with the second question: What are Web Services? , for obvious reasons.

WebServices are essentially pieces of logic(which you may vaguely refer to as a method) that expose certain functionality or data. The client implementing(technically speaking, consuming is the word) just needs to know what are the parameter(s) the method is going to accept and the type of data it is going to return(if at all it does).

The following Link says it all about REST & SOAP in an extremely lucid manner.

REST vs SOAP

If you also want to know when to choose what (REST or SOAP), all the more reason to go through it!