It describes how to construct URLs to get from one state to another (e.g. from a base URL to a list of songs, or from the list to an individual song). REST URLs are supposed to be opaque. A RESTful resource should provide links to its related resources for the user agent to navigate.

There's nothing wrong with what the author is trying to do, but it's nothing to do with REST.

Oops. That's one detail I missed in all those API tutorials. Thanks.

The canonical source is Roy Fielding's thesis, in particular chapters 5 and 6.

https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

> How does this miss the point of REST?

Because if it didn't, the full API description language would be:

  api-root: <url>

Or, for a pedantically detailed version:

  api-root: <url>
  media-types: 
      - <media-type>
      - <media-type>

Devil's advocate: "api-root: http://example.org/foo.raml" fits that bill.

Sure, for consuming the API - but does RAML have to be used this way? Couldn't RAML be used to generate test expectations or even (with tooling that probably doesn't exist) actually generate the API itself?

Are there any extant REST API's for which one could programmatically generate a client library based purely upon the root URL and media types?

> Are there any extant REST API's for which one could programmatically generate a client library based purely upon the root URL and media types?

For a truly RESTful API, the question you ask is somewhat incoherent. A client for a RESTful API consists of two key sets of components: functionality for sending and receiving resource representations to and from locations identified by URIs, and functionality for handling resource representations of particular media types. Assuming you have those, you don't need to "programmatically generate a client library" with the particular base URL of a particular API root, you access a URL that provides resources of any of the supported media types and your off to the races without programmatically generating anything.

Is this possible in practice for real implementations of RESTful principles? Yes, including the one that motivated the articulation of the REST principles, the WWW.

Is REST appropriate for all APIs? Maybe, maybe not. But its probably not useful to anyone to just call every web service that uses HTTP and isn't SOAP "RESTful".

This is a great question. Any answers would be illuminating. I've largely given up on the idea of hypermedia APIs that work like this, because the mindshare and tooling just doesn't appear to be there for it. I've never seen a client library that is based on following rels from a root, rather than generating URLs based on out-of-band information.