Introduction to the Hypermedia

At work, I had a conversation about implementing SOAP with an other service, It struck me that they did not talk about REST. Mostly in today's distributed systems, you may want to think twice about how to implement for the future. This is some thoughts I had on the matter

October 27, 2012

I was reading around about how to architect in a scalable fashion a web service. You know, the concept of remote procedure call?

At work, I had a conversation about implementing SOAP with an other service, It struck me that they did not talk about REST. Mostly in today’s distributed system, you may want to think twice about if there is something newer that solves better than a solution designed 20 years ago… there must be things learned

So, I wrote this small introduction to what is REST, and the Hypermedia.

Beware, I am not an expert, just a curious that found a nice video and some links about it and trying to learn and apply it properly.

Actually, I heard it for the first time from Darrell Miller in an impressive presentation that blew my mind. Unfortunately I did not pursue up until a few months ago.

Now, I am at a state where I am starting a project and we have to talk to many nodes, I would like to take this opportunity of starting from scratch and use it’s concepts. I am anxious on how it is going to look like.

As for the difference this post started for; I discussed with my colleagues, I compiled these two descriptions with code example in PHP to illustrate.

SOAP

SOAP is an object’s method call to a remote server as if it was a local object.

$o = new SoapClient('https://some.host/wsdl');
$clients = $o->getClients();

What you get at the is an understandable array, or text, or object coming from the web service.

Regardless of the other application SOAP server is in the same language as the client (PHP in this case).

This may seem nice, it has a few limitations on the regard of what you can do out of it.

REST

In contrast to SOAP, a REST call, you actually use HTTP to request things and use it’s content and headers to work your logic.

Situation is that most implementations only do a GET to a URL and that is all. A situation where most implementations do not fulfill all the power of it, again. This is the reason why the RESTafarians (passionate about REST) decided to change the name of it’s usages.

A nice way to explain the lacks of use of it’s potential through the popular implementation goes from Designing Hypermedia APIs presentation by Steve Klabnik.

Hypermedia

In comparison to REST, Hypermedia it is basically going like the following.

Popupar REST implementation would only care of sending a request and work with the received data, Hypermedia on the other hand, is like using what we receive and “browse” the content, follow links, submit forms to end up with the objective.

So, as an example:

use Guzzle\Http\Client;

$client = new Client('https://some.host/api/v1');
$request = $client->get('user/42348972389/profile/picture');
$request->setAuth('myusername', 'mypassword');
$image = $request->send();

With this example, you could get the RAW image file stream directly.

Libraries

Using Symfony2 in my projects all of this made me think about how to implement it, I stumbled on Guzzle and BUZZ, two PHP 5.3 libraries, which I could use. What I appreciate with Guzzle is the pattern around it’s usage.

As a side note, if you want to see an applied example of a REST call using Guzzle, you can see this post I created explaining my attempts. I did not work with that since then, I hope to get back to it soon.

Renoir Boulanger Un geek social et Linuxien de nature