pmuellr is Patrick Mueller, Senior Node Engineer at NodeSource.

other pmuellr thangs: home page, twitter, flickr, github

Wednesday, May 30, 2007

not doing REST

From Mark Baker:

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?

No comments: