REST and RESTful Web Services

Let’s start off by stating that a web service is a set of communication rules in the form of a deployed piece of software that lives in a computer or system which operates by exchanging specific information (in a specific format) with any other computer/system. Primarily, there two different set of rules when speaking of web services: SOAP (a protocol) and REST (an architecture). Now, when it comes to RESTful web services, there’s a subtle difference.

While REST (REpresentational State Transfer) refers only to the set of architectural principles, RESTful is an adjective, so to speak, used to describe any application or service on the Internet that follows or implements said principles to serve its purpose.

Just as SOAP, following the SOA (Service Oriented Architecture) principles, every RESTful web service should have at least the following characteristics:

• Loosely-coupled software modules.
• Always deployed as software services.
• Communication occurs over a network (typically).
• Modules interoperate and exchange data with another application.

Problems that REST solves

• Integration of legacy software or systems.
  • Written in different languages.
  • Running on different platforms or hardware.
  • Developed by different software teams or companies around the Globe.
• Development time shortened by using proven techniques and methodologies (standards).
• Complexity of implementation. REST principles allows for easy-to-implement, lightweight, high-performance and scalable web service solutions.
• Documentation. This is a widely known standard by developers and programmers around the world, so documentation on the Web is vast.

REST vs. SOAP

REST (Representational State Transfer)	SOAP (Simple Object Access Protocol)
Application clients interact with a RESTful web service entirely through the dynamic responses provided by the Server (HATEOAS principle).	Founded on the ACID philosophy (Atomicity, Consistency, Isolation and Durability), since it has been designed for complex and important transactions such as payment gateways, telecommunication services and identity management.
Not a web standard by itself; REST is just a set of architectural principles for providing and implementing a web service.	It is considered a Web Industry Standard by the World Wide Web Consortium (W3C), and also a messaging protocol.
Any media type allowed as data format. (JSON, XML, Plain text, HTML, etc…).	XML is the only allowed data carrier permitted.
More flexible when parsing response data.	Since its bound to XML only, parsing the response data is usually a bit more complex.
The data sent between the client and the server is called payload.	The data sent over is known as SOAP message must be wrapped in a specifically parsed and structured XML document, the envelope.
Its operations are available through links (URIs). Also known as resources.	Its operations and details are described in a standardized document named WSDL (Web Service Description Language).
It’s flexibility and lack of rules and standards allow for a way more simple implementation. Used by the big boys on the Internet: Amazon, Google eBay, Facebook, Yahoo!.	Due to its heavy set of rules and security standards, it is widely used by big Corporations and B2B Businesses (Banks, Insurance, Financial, etc.). One of the most common public SOAP APIs is from PayPal.
RESTful web services documentations are easier to understand.	Understanding a SOAP WSDL is usually more complex.

Architectural overview of RESTful Web Services

REST, as mentioned before is no more than an architectural style, and for that reason it lacks industry standard. You can read more about its architectural principles described by Dr. Roy Fielding in 2000 here.

• Every piece of information is a resource in the form of an URI (Uniform Resource Identifier). Just like any other link on the Web.
• Resources are manipulated using a fixed set of operations.
• It’s stateless. Meaning a task has to be completed in one call and there’s no state saved in memory as per the client application request.
• Runs typically over HTTP/HTTPS.
• Responds to HTTP verbs that allow for all possible CRUD (Create, Read, Update, Delete) operations on a resource.
• Available rest operations are: POST (Create), GET (Reads/Retrieves), PUT (Update), DELETE (Delete).
• JSON & XML are the two most typical data formats used, but actually any format defined by a media type is allowed.

Response Codes:

Since REST runs over HTTP, it always sends back an HTTP response; meaning that it will contain one of the most commonly known HTTP status codes.

GET.

Retrieves the information (resource) requested in the URI and typically responds with a HTTP 200 Code (OK) along with the data in the response body.

PUT.

Updates the resources. And responds with a 200 / 204 (No Content) status code.

POST.

Creates the resource and typically responds back with 201 (Created) or 204.

DELETE.

Deletes the resource and typically responds with 200, 202 (Accepted), or 204

Each REST method described above must be identified by an URI (URL path). For instance; let’s assume the following is an existing web service on the Internet.

http://historicalbooks.net/api/rest (Base URL)

In order to retrieve all the books available the service should has a path already defined. 
Something like, http://historicalbooks.net/api/rest/getBooks

So the path /getBooks is the method (identifier) used of respond to the GET verb.

The same applies for all the other HTTP verbs. Every single one must have its unique identifier (URI)

We can conclude that REST is one of the most used architectures for web services now a days. Fortunately, there are tons of resources and documentation for platforms-specific implementation such as Java or C#. Here at ReadingInBits you’ll be able to find a couple of tutorials on how to set up a RESTful web service using both Java and C# languages. Stay tuned.