WhatfettleWhat I Believe Roy Said

Roy Fielding is on something of a crusade, pushing back on many publishers of HTTP interfaces who claim to be RESTful. I particularly like the latest: REST APIs Must be Hypertext Driven. Unfortunately the Word of Roy may be a little too divine for comprehension by many sinners, so at the risk of invoking the wrath of the posse, I’ll try and simplify.

If you insist on using the word “REST” in association with your API, ensure you:

Notes, or how The Web subverts REST:

  1. It isn’t a knife-edge, but often what differentiates meta-data from a form is a form is a document with links to actual resources, served as part of an interaction with a Web site, close in time before the interaction. It’s a moot point if descriptions such WADL or WSDL are forms or meta-data, but most people would say the latter because they’re often abstract, baked into software and don’t give a human that click-through experience in a browser.
  2. I suspect authentication tokens may be just about acceptable as external state, but only use a widely adopted scheme, usable in browsers such as OpenID and OAuth for delegation, though it’s arguable exactly how RESTful these schemes are.
  3. It’s arguable that a HTML form with an action of GET is a way of templating URIs, and we all think that’s fine – see note 1.
  4. Practically speaking, my experience of my profile page isn’t always going to be your experience of my profile page. The state introduced by authentication changes that.

Of course some more puritanical souls like myself would question the use of the word “API”, after all, The Best Web APIs are just Web Sites.