Know what Web Services are¶

A "Web Service" is a client-server application that uses the HTTP protocol for communications between client and server. More specifically, the client attempts to open a TCP connection to a pre-defined host and port where the server is listening. Once a connection is open, the client and server communicate in HTTP.

Web Services can run on any TCP/IP network - the public Internet is one example, but many Web Services run on corporate intranets, for example. A developer will typically have an isolated testing network on his own machine, etc.

Know what a RESTful Web Service is¶

Before you write a REST server, you should probably learn what a REST server is. Here is a crash course.

Even if you _think_ you know what a REST server is, it might be useful to either skim this crash course or, even better, just read Leonard Richardson's paper <http://www.crummy.com/writing/speaking/2008-QCon/act3.html> which this "crash course" attempts to paraphrase.

Introduction

REST is an approach to implementing client-server software architecture, in which communications between client and server use the HTTP protocol. It turns out that HTTP is "good enough" for many applications, and using it can save a lot of work.

I urge all prospective REST server developers to study and "grok" the Richardson REST Maturity Model <http://www.crummy.com/writing/speaking/2008-QCon/act3.html>, since it is the conceptual basis for this discourse.

More than a web server

Providing a Web Service implies having a web server. Web::MREST does this for you, with help from Web::Machine and Plack.

But the mere presence of a web server does not make a Web Service "RESTful".

Level 0: tunnelling mechanism

Some notorious Web Services - such as those based on the XML-RPC and SOAP technologies - use HTTP as a tunnelling mechanism. In this paradigm, each client message is serialized and sent to the server in the body of a "POST" request. The server always responds with a 200 status code, which in this case signifies no more than that the message was received and processed, and the server's serialized response is placed in the response body.

Richardson calls this "One URI, one HTTP method".

Example HTTP request:

    Method:       POST 
    URI:          http://myapp.example.com/
    Header:       Accept: application/json
    Body:         { 
                      "command" : "employee.insert",
                      "arguments" : { ... }
                  }

Example HTTP response:

    Status code:  200 OK
    Content-Type: application/json
    Body:         {
                      "status" : {
                          "level" : "ERROR",
                          "code" : "MYAPP_INSUFFICIENT_PRIVS",
                          "text" : "Insufficient privileges"
                      }
                  }

To quote Richardson:

    If you look at an XML-RPC service, or a typical SOAP service . . ., you'll
    see something that looks a lot like a C library. There are a bunch of functions,
    sometimes namespaced with periods. All of these functions are accessed by
    sending a POST request to one single URI.

Level 1: resources

The next step, which Richardson calls "Many URIs, one HTTP method", involves moving some part of the XML/JSON body into the URI. Though this step might seem insignificant, calling it "revolutionary" would be closer to the truth.

Let's apply this to our example. If employees can be uniquely identified by their nick, a request for employee "simona" might look like this:

    Method:        POST
    URI:           http://myapp.example.com/employee/nick/simona
    Header:        Accept: application/json
    Body:          {
                        "command" : "GET"
                   }

By moving the object specification to the URI, the object becomes a web resource, and this is what makes it "revolutionary".

The very purpose of the HTTP standard is to facilitate the publishing and manipulation of web resources, and the URI is the "Uniform Resource Identifier". Moving from level 0 to level 1 involves the same paradigm shift as embracing OO principles in your code.

But even if you already were using OO principles in the underlying code, what benefit is there in bundling the object identifier in the HTTP request body? The Uniform Resource Identifier (URI) is the right tool for that.

Level 2: HTTP verbs

If you know about HTTP methods, the previous example should cry out to you (or, rather, you might cry out to it): "why are they using "POST" for a GET request?!" And, while it may seem astonishing, that is exactly what many Web Services do (or used to do before Richardson published his influential paper).

The next "level" in Richardson's structure involves leveraging HTTP methods to distinguish read requests, which should be idempotent, from write requests, which modify the underlying data. When this distinction is hidden in the API, there is no way for client code to optimize read-only requests.

Illustrating with our example:

    Method:        GET
    URI:           http://myapp.example.com/employee/nick/simona

The barest glace is enough to make it obvious that this request is far simpler than its level 1 equivalent. At level 2, the server guarantees that GET requests will never change the data, and that means your client code can dispense with whatever special precautions it needs to take to prevent unwanted modifications.

Richardson's designation for this level is: "Many URIs, each supporting multiple HTTP methods". Quoting Richardson again to drive the point home:

    The web is powerful because it gives you tools for splitting the inherent
    complexity of a task into small chunks. The URI lets you give a name to
    every object in the system. With URIs, every object can be a little bit 
    complex. That's the URI level. On the HTTP level, the major advance of the
    web is that although it can handle any kind of operation, it splits out
    read operations, operations that want to fetch data, and treats them specially.

Taking our example a little bit further, let's say we want to create a new employee at this level. Here's what the request might look like:

    Method:        PUT
    URI:           http://myapp.example.com/employee/nick/george
    Header:        Accept: application/json
    Body:          {
                       "name" : "George III",
                       "occupation" : "King of England"
                       ...
                   }

The important point here is that the request body now contains content only - no command or function name. The role of the function name is taken over by the combination of HTTP method and URI.

Now we are really using HTTP to its fullest potential. Or are we?

Level 3: hypermedia controls

Until this point, the discourse has been easy to follow. Yet, Richardson describes a third level, "hypermedia", which he defines as:

    Resources describe their own capabilities and interconnections

This is also sometimes referred to as "Hypermedia As The Engine Of Application State", or HATEOAS. As Richardson himself acknowledges, this is where the enthusiasm starts to fade.

According to Richardson, whereas level 1 is "the lesson of URIs" and level 2 is "the lesson of HTTP", the lesson we learn at this level is "the lesson of HTML". That is because HTML is an example of hypermedia controls that we are all familiar with. Generalizing this, we can say that a HATEOAS client "navigates" its server very much like a human surfs the web, that is: by parsing and following links. Just like on the WWW, in a HATEOAS application, resources link to other resources and, crucially, those links are expressed as URIs.

Returning to our example, let us say that our employee objects link to occupation objects. Inside the database, each occupation is identified by its "occupation_id", an integer value, and linked tables use this as a foreign key. Without hypermedia controls, our request for employee "george" and the server's response (the part following the '*') might look like this:

    Method:        GET
    URI:           http://myapp.example.com/employee/nick/george
    *
    Status code:   200 OK
    Content-Type:  application/json
    Body:          {
                       "name" : "George III",
                       "occupation_id" : 553,
                       ...
                   }

In HATEOAS, the same request/response might look like this:

    Method:        GET
    URI:           http://myapp.example.com/employee/nick/george
    *
    Status code:   200 OK
    Content-Type:  application/json
    Body:          {
                       "name" : "George III",
                       "occupation" : {
                           "link" : {
                               "href" : "http://myapp.example.com/occupation/catalog/553,
                               "rel" : "http://myapp.example.com/occupation",
                               "name" : "King of England"
                            },
                       ...
                   }

While at first glance it seems more complicated, this approach (which we will call the HATEOAS approach) is superior to the non-HATEOAS approach illustrated by the first example.

In the non-HATEOAS version, the client code needs to know that occupation objects are identified by their 'occupation_id' property. Further, to gain access to the object it needs to know how to transform the occupation ID into the appropriate resource so it can issue a GET request for it.

By putting the full URI of the occupation resource into the response, the client no longer needs to know any of that. To get the resource, it directly issues a GET request to the URI provided in 'href'.

But the "link" property gives us more than this. From the additional properties the client can, for example, derive that the resource can be modified by issuing a "POST" request to "http://myapp.example.com/occupation" and including the "name" property (with the value "King of England") in the request body.

The non-HATEOAS variant, by contrast, provides nothing more than a number. The "knowledge" of what can be done with it must be embedded in the client code. As Richardson notes, this makes client code more brittle. He cites examples of RESTful Web Service projects where clients were abandoned after being broken repeatedly by server-side changes to the REST API.

Conclusion

There is more that can be done with the HATEOAS approach, of course, than provide URI links in the HTTP response. The idea is for clients to get information on their state from the server via HTTP. This should make the clients less prone to breakage when changes are made on the server side.