3 ms·

How does this miss the point of REST?

danellis 11y ago
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.
- SeldomSoup 11y ago
  Oops. That's one detail I missed in all those API tutorials. Thanks.
  - danellis 11y ago
    The canonical source is Roy Fielding's thesis, in particular chapters 5 and 6. https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
dragonwriter 11y ago
> 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>
- philwelch 11y ago
  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?
  - bct 11y ago
    https://www.ietf.org/rfc/rfc5023.txt https://www.ietf.org/rfc/rfc5023.txt
  - sanderjd 11y ago
    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.
  - dragonwriter 11y ago
    > 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".
- muaddirac 11y ago
  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?
- tveita 11y ago
  Devil's advocate: "api-root: http://example.org/foo.raml" http://example.org/foo.raml" fits that bill.

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.

SeldomSoup 11y ago
Oops. That's one detail I missed in all those API tutorials. Thanks.
- danellis 11y ago
  The canonical source is Roy Fielding's thesis, in particular chapters 5 and 6. https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

dragonwriter 11y ago

> 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>

philwelch 11y ago
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?
- bct 11y ago
  https://www.ietf.org/rfc/rfc5023.txt https://www.ietf.org/rfc/rfc5023.txt
- sanderjd 11y ago
  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.
- dragonwriter 11y ago
  > 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".
muaddirac 11y ago
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?
tveita 11y ago
Devil's advocate: "api-root: http://example.org/foo.raml" http://example.org/foo.raml" fits that bill.