Thursday, May 31, 2007

Does REST need a DL? No, just Signposts.

REST (err, the Web) does not need a Description Language.

But wouldn't it be so nice to have one! Sure, until you want to change anything. A DL couples the client to the server, and forces stability of everything defined by the DL.

The REST style encourages loose coupling, independent evolution, and uniform interfaces. The "hypermedia as engine of application state" is the opposite of a DL.

How is a DL so bad? A DL is used to generate code (stubs/skeletons) at design time. After that, any changes to the URI or data values on the server side will brake any clients.

So what's my great idea? Use a micro-format as machine signposts.

Links and forms could be marked with a set of class attributes that convey the common machine processing activities. I'm thinking about common stuff like:
  • login/logout
  • parts (list, name, id number, related parts links, specification link)
  • checkout/ordering (mailing address, billing address, credit card info)

As an example, if I have a shopping site with a list of parts and a checkout form, something like this (in pig-xml for easy web typing):
[div class="part"]
[div class=""]Super Espresso Machine[/div]
[div class="part.number"]42[/div]
[a class="part.specification" href="42/specification"]Part specification[/div]
[form class="" action="order/42" method="post"]
[input type="submit" value="Submit"]Add to Cart[/input]
[div class="part"]

[form class="checkout" action="buynow" method="post"]
[input class="fullname" type="text" name="fullname"/]
[input class="mailing.address" type="text" name="mailing-address"/]
[input class="billing.address" type="text" name="billing-address"/]
[input class="creditcard.number" type="text" name="creditcard-number"/]
[input type="submit" value="Send"/]

I could write a personal shopping agent that picked parts by id and followed the "checkout" action (form) filling in anything that was already known (like addresses and cc info).

Why can't I do the same thing with a DL?!? Sure, you could. Until the server added a confirmation page after the first form. Something like:
[form class="checkout" action="buynow.confirm" method="post"]
[input type="submit" value="Send"/]

A human would take that in stride, but a DL wouldn't already be coded to handle that. The agent that's just following signposts would easily be able to cope with this change.

A signpost following agent would, once it decided to follow the "checkout" action keep on following it, filling in recognized data values as it progressed. That is until a success or error response is found. Oh, must add a "success" signpost to my list.

Couldn't a web site just provide a DL exposed service point and the HTML exposed service? Sure, but, that would be more work, right?


Mark said...


Mike Schinkel said...

@John: How is a DL so bad? A DL is used to generate code (stubs/skeletons) at design time. After that, any changes to the URI or data values on the server side will brake any clients.

Why is code gen a foregone conclusion? Why can't a DL be processed each time? I really don't see the distinction between the two.

But anyway, I think I'm 100% in agreement with your ideas, just not sure I agree that what you are doing is not a DL or that DL implies code gen.