sgo.to

ROWS

Sam Goto

Resources-Oriented Web Services (ROWS) is a set of technologies that enable the programmatic discovery, description and invocation of actions on resources.

It connects the human web with the programmable web. It is an alternative to Service-Oriented Architectures that is more aligned with how the web works (URLs and A Uniform Interface: REST. The "R" in URL is the key part.).

This is part of a series of posts. You want to read this and this before carrying on.

This is a human-readable walk through of a slightly more technical specification (build).

What Problems Are We Set To Solve Again?

Our goal is to connect the "human web" to the "programmable web". Our challenge is to automate what we currently do manually as humans.

We, as a community, haven't yet converged on the following:

  1. A general framework, a way for each individual service to tell clients about its resource design, its representation formats and the links it provides between resources.
  2. A language with a vocabulary that can describe the variety of RESTful and hybrid services. A document written in this language could script a generic web service client, making it act like a custom-written wrapper. More specifically, we'll need to tell clients:
  • What semantic operations are available to be performed
  • Which HTTP method to use
  • What the expected entity-body looks like
  • What to expect to get back after you invoke

Lets Look At What Our Starting Point Looks Like

The human web starts by using a browser to send a GET request to a resource via a URL. Lets say you were looking for booking a cab, here is what you'd do under the hoods:

GET /mountain-view HTTP/1.1
Host: www.yellowcab.com

And the server responds:

HTTP/1.1 200 OK Content-Type: text/html

With:

<html>
<body>

<span>Welcome to Yellow Cab Mountain View!</span>

<a href="/moutain-view/reservations">
Click here to book a cab!
</a>

</body>
</html>

Now, that's great for humans to consume, but a computer can't tell the difference between this and a web page about frogs.

Enter JSON-LD, Microdata And Schema.Org

The first step to help computers make sense of this page is to tell it explicitly what this is about.

There are a few good methods for transporting linked-data in HTML, but my favorite are JSON-LD and microdata*.

I think that JSON-LD is a more scalable approach overall for large/complex instances, but microdata is easier to grasp on simpler examples. So I'm going to use microdata here in my examples, but bear in mind that I actually prefer JSON-LD a lot better in practice.

That alone isn't sufficient. You need a machine readable description of a taxi stand. Something that a computer could understand. This is where schema.org comes in: it provides a vocabulary that describes things in the universe in a manner that computers can digest.

This is what this web page would look like:

HTTP/1.1 200 OK
Content-Type: text/html

<html>
<body itemscope
    itemid="/mountain-view"
    itemtype="http://schema.org/TaxiStand" >

<span itemprop="description">
Welcome to Yellow Cab Mountain View!
</span>

<a itemprop="reservations"
  href="/mountain-view/reservations"
  itemscope itemtype="http://schema.org/ItemList">
Click here to book a cab!
</a>

</body>
</html>

Now, this basically addresses problem #1 I raised above. It gives you a general framework (json-ld/microdata + schema.org) to describe things in a manner that computers can understand.

A computer now knows:

  • This resource is a TaxiStand
  • This TaxiStand has a description
  • This TaxiStand has an ItemList of reservations

But it doesn't yet know what it can do with it.

The Link To The Programmable Web

The programmable web exists in APIs, but it can't be easily found by computers. So, lets add a link between this specific taxi stand and where it can be found in the yellow cab APIs:

<body itemscope
    itemid="/mountain-view"
    itemtype="http://schema.org/TaxiStand" >
  <meta itemprop="alternate" itemscope 
    itemtype="http://schema.org/ApiUrl"
    content="http://api.yellowcab.com/moutain-view"/>

Now we know that this Taxi Service is linked to a specific API.

If you GET-ed that URL you'd get something like the following:

GET /mountain-view HTTP/1.1
Host: api.yellowcab.com

And the server responds:

HTTP/1.1 200 OK
Content-Type: application/json+ld
{
  "@context": "http://schema.org",
  "@type": "TaxiStand",
  "@id": "/mountain-view",
  "description": "Welcome to Yellow Cab!",
  "reservations": {
    "@type": "ItemList",
    "@id": "/mountain-view/reservations",
  }
}

That's much more like what computers can understand. There is a Content-Type header that tells computers how to parse it and inside the hypermedia there is machine-readable information about the resource.

But, can a computer tell what to do with these resources?

If You Wanted To Create A Reservation, How Far Would HTTP Take You?

The closest to an API discovery mechanism in HTTP is the OPTIONS request.

OPTIONS /mountain-view/reservations HTTP/1.1
Host: api.yellowcab.com

And it could respond:

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST

POST requests can take you a long way, but as LSM pointed out earlier, it is not sufficient. How would you know:

  • What entity-body the POST request takes?
  • Whether POST is not an overloaded POST (e.g. RPC-Style POST)?

Introducing Actions

Actions gives you the vocabulary to describe what can be done with resources. It doesn't require you to make an extra request, but it is rather attached inline with the resources.

It consists of three core mechanisms:

Here is what the JSON-LD response could look like:

HTTP/1.1 200 OK
Content-Type: application/json+ld
{
  "@context": "http://schema.org",
  "@type": "TaxiStand",
  "@id": "/mountain-view",
  "description": "Welcome to Yellow Cab!",
  "reservations": {
    "@type": "ItemList",
    "@id": "/mountain-view/reservations",
    "operation": {
      "@type": "CreateAction",
      "expects": {
        "@type": "SupportedClass",
        "subClassOf": "http://schema.org/TaxiReservation",
      }
    }
  }
}

You could have also equally found that information in the HTML markup *:

 <a itemprop="reservations"
  href="/mountain-view/reservations"
  itemscope itemtype="http://schema.org/ItemList">
  <meta itemprop="alternate" itemscope 
    itemtype="http://schema.org/ApiAppUrl"
    content="http://api.yellowcab.com/moutain-view/reservations" />
  <div itemprop="operation" itemscope 
    itemtype="http://schema.org/CreateAction"/>
    <meta itemprop="expects" itemscope 
      itemtype="http://schema.org/SupportedClass"
      content="http://schema.org/TaxiReservation"/>
  </div>
  </div>
Click here to book a cab!
</a>

I agree that this looks a bit verbose, but I'll show you later how to make this more concise. Hint: it has to do with linked data.

Now, that tells you everything a computer needs:

  • This is a TaxiStand.
  • There is an API entry point here http://api.yellowcab.com/moutain-view/
  • This TaxiStand has an ItemList of reservations.
  • The reservation's ItemList takes CreateAction operations, which has very specific semantics (as well as a specification of what it means to invoke it, e.g. it is tight a POST request because it was defined that way).
  • To create a reservation, you pass an instance of a TaxiReservation.

Which means that from this information a computer can send a request like the following with confidence:

POST /mountain-view/reservations HTTP/1.1
Host: api.yellowcab.com
Content-Type:application/json+d;charset=utf-8
Content-Length:207
{
  "@context": "http://schema.org/",
  "@type": "TaxiReservation",
  "pickUpLocation":
    "1600 Amphitheatre Parkway, Mountain View, CA",
  "pickUpTime": "2pm",
  "numberOfPassengers": "1"
}

And the server should respond something like the following:

HTTP/1.1 201 Created
Location:
http://api.yellowcab.com/moutain-view/reservations/32523325225

This Is Where Hypermedia Comes In Again.

Hypermedia is an extremely powerful concept. It allows you to hop from one resource to another following links. That's quite powerful.

You just got a resource created, lets take a peak at what it can do:

OPTIONS /mountain-view/reservations/32523325225 HTTP/1.1
Host: api.yellowcab.com

And it could respond:

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, PATCH
Accept-Patch: application/json+ld

And you'd be quite excited knowing that this is a mutable resource because it takes a PATCH HTTP method.

It tells you additionally that it takes a JSON-LD patch document, which is quite informative too.

But as much as with POST, you wouldn't know enough what is the application semantics of the PATCH operation (e.g. what does it mean to "patch"? is it to update the pick up time? the drop off location?).

Enter actions again. Lets GET this resource:

GET /mountain-view/reservations/32523325225 HTTP/1.1
Host: api.yellowcab.com

And now the server can respond to you:

HTTP/1.1 200 OK
Content-Type: application/json+ld
Accept: application/json+ld
{
  "@context": "http://schema.org",
  "@type": "TaxiReservation",
  "@id": "/mountain-view/reservations/32523325225",
  "reservationStatus": "CONFIRMED",
  "operation": {
    "@type": "CancelAction"
  }
}

And because there is a very specific application semantic for CancelAction ("The act of asserting that a future event/action is no longer going to happen.") and a very specific definition of what it means to "cancel" a resource (in HTTP terms it is a PATCH request, according to the definition of "canceling"), it is well defined for a computer to send a PATCH request like the following:

PATCH /mountain-view/reservations/32523325225 HTTP/1.1
Host: api.yellowcab.com
Content-Type:application/json+d;charset=utf-8
Content-Length:100
Accept: application/json+ld
{
  "@context": "http://schema.org/",
  "@type": "CancelAction"
}

Which now sets the state of the reservation to cancelled:

HTTP/1.1 200 OK
Content-Type: application/json+ld
{
  "@context": "http://schema.org",
  "@type": "TaxiReservation",
  "@id": "/mountain-view/reservations/32523325225",
  "reservationStatus": "CANCELLED",
}

Note too that, once you cancelled, the "CancelAction" operation goes away, because that operation is no longer applicable to a CANCELLED reservation.

To Wrap Things Up

Phew, that was a lot of information. Here is where I think things fit:

+------------------------+
|         Actions        | <- [missing gap #2](/2014/02/the-gaps-in-resource-oriented-architectures.html)
+------------------------+
|         Things         | <- [missing gap #1](/2014/02/the-gaps-in-resource-oriented-architectures.html)
+------------------------+
|         JSON-LD        | <- hypermedia
|        microdata       |
+------------------------+
|          REST          | <- [ROA vs SOA](/2014/02/the-w-stands-for-web.html)
+------------------------+
|          HTTP          | <- URIs, methods
+------------------------+

OK, That Was An Interesting Read. But ...

... there is so much more to talk about.

The devil is on the details and we haven't gotten yet to how things like collections, authentication, different transport mechanisms (e.g. mobile applications, email messages) and gap #3 should look like.

Stay tuned. More to follow.