Roy Fielding: “What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?”

In other words, if your API isn’t returning documents that point to other resources using URIs, then it’s not RESTful.

An example of “almost-but-not-quite” RESTful API: suppose you have a call to get a collection of widgets in a catalog system called GET /widgets. Now suppose that the call returns an XML document representing a collection of widgets, each with its own part number, description, etc.

If you are a client, how do you know how to access a widget represented in the collection in order to

• retrieve more details about the widget
• update the widget’s data
• delete the widget

If you answered “synthesize a URI from its part number using a document describing the API”, then you’re doing it wrong. In a RESTful API, each item in the collection must have its URI spelled out for the consumer, so the consumer can figure out how to work with that resource without having to build in unnecessary coupling. After all, if you have the widget’s URI, you can call GET, PUT, or DELETE on the URI with predictable results.

I’m sure Roy’s post is going to generate a lot of heat and light, so it’s worth reading it (and the comments that ensue).