RESTful and SOAP, etc

Hello, Kris.

REST (representational state transfer) in its most basic form is a way of explaining the architecture of the World Wide Web. It ignores how components work and how precisely they communicate, instead it focuses on their roles and constraints.

What this means, is that REST has nothing to do with the programming language, server software or anything like that. It doesn't care about those. What it does care about are these architectural constraints (rules):

Client-server model — there is a clear difference between a server and a client. The server holds the data, the client doesn't. The server has nothing to do with the user interface, this is all contained in the client. This allows for a simpler server and separate development. Different clients can be created for specific needs, all communicating with the same server, getting the same data, but showing it and interpreting it in a different way. It also means that the server can be developed independently from the client and vice versa. Finally, both the client and the server can be replaced if necessary, as long as the same rules are followed.

Statelessness — this is a characteristic of communication between the client and server. Usually, a communication protocol mandates that a client "introduces" itself to a server (handshake). Some form of session is formed between the client and the server so that the server can keep track of that particular client. In a stateless protocol, there is no such context stored on the server. In REST, every request from a client to a server is treated as independent. It's completely unrelated to any prior requests. No session exists in the traditional sense. The server doesn't keep state internally, hence the name.

Cacheability — this one is fairly simple. When you browse the web, your Internet browser stores some of the data on your hard drive for faster loading if you re-visit a page (this is an oversimplification, but that's the gist of the concept). It also reduces the number of requests towards the server. Any responses in REST have to have the ability to be cached. Or, in case of volatile data (data that shouldn't be too old), responses should be able to forbid caching, so that the user always gets up-to-date data.

Layered system — a client should not be able to tell if it's connected to the end server or to some intermediary. When dealing with large systems that get a lot of traffic, it's normal to have several servers that take the load off the main server, or in completely distributed systems, a main server may not even exists. The client doesn't care what actual machine it's communicating with, only that it's communicating with the system.

Uniform interface — this is probably the most important part of REST. The server must be able to provide data in a form that the client can understand. It has to be identifiable by the client as well. This form is usually not the one that the server uses for storing the data internally. Once the client receives a resource, it must have enough data to be able to modify or delete that resource (if it's allowed to do so). Resources should also describe themselves so that the client knows how to use them.

Applications that conform to these rules are called RESTful.

In the context of web programming, RESTful services are usually defined by the bar URI, data type and HTTP methods (GET, PUT, POST, DELETE).

To put this all together, let's say you have a web application that has a RESTful interface. An example of how this would work looks like this.

The base URI could be http://www.myapp.com/api/v1. To interact with users stored on the server, you'd most likely use a /user route.

Retrieving information about the user with the id 17 would mean GETting http://www.myapp.com/api/v1/user/17. The response from the server would probably be a JSON document containing the name of the user, link to the profile photo, bio and so on. This data could be cached except for the user's status which could change, so any further access to that user's profile would use the cached profile data, but it would request a new status (if one exists).

That same user could delete his/her profile by using the DELETE method on the same route (the server would then check if that user has the authority to do so). Updating the profile would mean using the PUT method on that route.

Getting a list of all the users would probably be a GET request to the base /user route, without any ids or any other parameters. This information could be cached because you're probably only interested in the user names and IDs.

And finally, creating a user would be a POST request to the /user route.

All these requests would include an authorisation token, to let the server know who's making the request. The server wouldn't keep any state on this, it would authorise each request independently based on the token.

Additionally, the client would access any other resources in the same manner. For example, posts would be available by _GET_ting http://www.myapp.com/api/v1/post — a URI that follows the same scheme as the users route, thus satisfying the uniform interface rule.

The whole concept can be hard to understand without some experimentation, but it's really not as complicated as it sounds. I hope my explanations cleared this up a bit for you.

SOAP on the other hand is a protocol, not an architectural style. This means that it's a clearly defined way of exchanging messages. As such, it's a bit more complicated. I'm only mildly familiar with it, so I won't even attempt to explain how it works.

I can't remember any Treehouse lessons dealing with SOAP, but there are some that deal with RESTful services:

• Building with AngularJS and APIs guides you through building an AngularJS app that communicates with Dribbble's API
• Build a Photo Browser iPhone App deals with Instagram's API

There might be other videos/lessons on the topic of REST (usually any videos covering various APIs).