Links

Wednesday, May 30, 2007

not doing REST

So if you're writing (or generating) contract/interface-level code which
can't late-bind to all resources, everywhere, you're not doing REST ...

Is this "We don't need no stinkin contracts!" meme a reaction to the non-web-friendly
WS-* world, what with it's overly complex and verbose schemas? Because I think there's
plenty of room for some people to apply contracts to parts of the web. I certainly
don't believe the entire web can be fully described using some all-encompassing schema language; but small
pieces? Sure.

I guess what I don't understand, is how you are supposed to describe your services
to someone without some kind of meta-data describing the service. Every 'web api'
I've ever seen has human readable text describing
the URIs, the data expected as input, and the data expected as output.
(Admittedly, most of these 'web api's violate best practice HTTP principles somehow, but I think that's not
an issue here; they could all be refactored to be be better HTTP citizens.)
That human readable text is
a contract; an interface. In English. Which is terrible. I'd rather have a machine readble
version of that contract, so I can generate something human readable from it.
And perhaps a validator. And some client stubs. Maybe some some test cases.
Diagnostic tools. Etc.

What is the the alternative to describing your services?
How is anyone going to write code to use these services, if they don't know where
to send requests, what verbs to use, what data to send, and what kind of data to expect?
Instead of Flickr producing a description of their web services
like this, they're simply supposed
to say "Flickr is now fully REST-enabled. Start
here, and have fun!" ??

As with
data modelling,
I don't feel like there is a single answer to what schema or contract language
be used. I'm not initially sold on WADL (seems too verbose), and certainly wouldn't
use it if there
was something else, better, for whatever project I was working on.
The shape of
the schema language isn't important, as long as it works for you.

So I guess contract-driven HTTP interfaces aren't REST. But this is an area
I'm interested in; what name should I use, so I can avoid be labelled as
"not doing REST" while I'm optimizing my use of the web by being a good
HTTP citizen?