5 ms·

The example demonstrates an RPC-style HTTP API with pretty URLs. There's no hypermedia in sight. Oh well, we'll figure it out one day... That being said, this

The example demonstrates an RPC-style HTTP API with pretty URLs. There's no hypermedia in sight. Oh well, we'll figure it out one day... That being said, this is exactly the sort of documentation that's helpful for this kind of API.

coolgeek 15y ago
Just so that I'm clear on this, are you just criticizing that all requests go to /word.json? IOW, would the following be RESTful? GET /entries/{word} # Return entries for a word GET /wordForms/{word} # Rturn other forms for a word POST /wordForms/{word} # Adds a relationship map for a word
- arethuza 15y ago
  I think the point is that if you are documenting the structure of URIs you are focusing on the wrong thing - a RESTful interface documentation should mostly be about the hypermedia (HTML, XML, JSON,...) that the URIs are embedded in - a particular server should really have the freedom to construct the URIs in any way it wants and still have clients that understand the API work. See: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
  - smhinsey 15y ago
    I think when done right (a subjective measurement, to be sure) the only URI you care about for a RESTful API is the root, because the API's resources are defined, along with how they can be manipulated, in the root response or can be transitioned to from there in some way that is defined there.
    - jcromartie 15y ago
      Yes, that's the key. If the media types are documented (like how browsers and developers understand HTML forms) then you don't need to document every single corner of the API. You can offer a good definition of the media types, and let the resources and links do the rest.
chubot 15y ago
That's the theory... but the gaping hole is that JSON doesn't define hyperlinks like HTML does. Also, I think Subversion tried to make resources discoverable from the root with WebDAV, but it just leads to crazy latency with all the round trips, and everyone agrees it was a mistake. Any APIs you can point to that actually use "hypermedia" and are successful? Most good APIs I've seen just define a bunch of simple JSON endpoints with predictable URLs.
- jcromartie 15y ago
  http://code.google.com/apis/gdata/ http://code.google.com/apis/gdata/ http://kenai.com/projects/suncloudapis/pages/Home http://kenai.com/projects/suncloudapis/pages/Home I don't know how successful they are.

coolgeek 15y ago

Just so that I'm clear on this, are you just criticizing that all requests go to /word.json? IOW, would the following be RESTful? GET /entries/{word} # Return entries for a word GET /wordForms/{word} # Rturn other forms for a word POST /wordForms/{word} # Adds a relationship map for a word

arethuza 15y ago
I think the point is that if you are documenting the structure of URIs you are focusing on the wrong thing - a RESTful interface documentation should mostly be about the hypermedia (HTML, XML, JSON,...) that the URIs are embedded in - a particular server should really have the freedom to construct the URIs in any way it wants and still have clients that understand the API work. See: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
- smhinsey 15y ago
  I think when done right (a subjective measurement, to be sure) the only URI you care about for a RESTful API is the root, because the API's resources are defined, along with how they can be manipulated, in the root response or can be transitioned to from there in some way that is defined there.
  - jcromartie 15y ago
    Yes, that's the key. If the media types are documented (like how browsers and developers understand HTML forms) then you don't need to document every single corner of the API. You can offer a good definition of the media types, and let the resources and links do the rest.

chubot 15y ago

That's the theory... but the gaping hole is that JSON doesn't define hyperlinks like HTML does. Also, I think Subversion tried to make resources discoverable from the root with WebDAV, but it just leads to crazy latency with all the round trips, and everyone agrees it was a mistake. Any APIs you can point to that actually use "hypermedia" and are successful? Most good APIs I've seen just define a bunch of simple JSON endpoints with predictable URLs.

jcromartie 15y ago
http://code.google.com/apis/gdata/ http://code.google.com/apis/gdata/ http://kenai.com/projects/suncloudapis/pages/Home http://kenai.com/projects/suncloudapis/pages/Home I don't know how successful they are.