$ curl https://api.github.com/repos/github/gollum/issues -i
HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.github.com/repos/github/gollum/issues?page=2>; rel="next", <https://api.github.com/repos/github/gollum/issues?page=3>; rel="last"It's sad that it didn't happen in XHTML2, and also removed from HTML5.
If you say "erb", please don't be offended by me laughing.
It's also worth noting that to_json should not be invoked directly these days in favor of as_json. It's now meant to more or less be an internal Rails API.
OK, I am only half-kidding. Have you seen RABL? I've been meaning to play with this. http://blog.dcxn.com/2011/06/22/rails-json-templates-through...
Looks perfect.
Content-Type: application/vnd.acme-json-with-paged-hrefs
that means that all "href" properties are URIs that may be paged by appending "?page=NNN" to them. If both server and the client understand this content-type, the representation may omit the "rel:" part from the parent example altogether.Constructing arbitrary URIs by the client is not RESTful; however in this case it's the server-side that is in control of URI generation mechanism (it could serve a different representation, with a different Content-Type:, if it chooses to) -- thus it's perfectly valid from the REST point of view.
This is the same story as with the HTML <form> element. It also allows client to construct URIs by the specific rules known to both sides -- because the rules are defined by the appropriate standards about text/html.
But to the extent that they are all "lame database serialization" layers, I'd have to say "well - ya". REST is kind of just that.
I think that what you're really trying to say is that implementations you have found don't do HATEOAS.
I'm designing the API for Poll Everywhere right now. Internally a multiple choice poll resource consists of several database tables and Rails models, but I simplified the externally facing JSON representation down to:
{
multiple_choice_poll: {
title: "Fav color?",
options: ["Red", "Blue", "Green"],
sms_enabled: true
}
}
Had I followed Rails REST conventions, I'd have an overly complicated chunk of JSON.I'd love to implement a full HATEOAS stack on Ruby/Rails; we'll see if I get around to it.
---
BTW In case anybody needs to Google HATEOAS (like I did): http://en.wikipedia.org/wiki/HATEOAS
I could wish that Rails had a cleaner path and this regard, though. I've never understood the thought process behind Rails' serialization system. Why use MVC to deal with html and email but almost ditch it entirely for other document formats? Especially when we're dealing with something that could really benefit from embedded hyperlinks.
But ... there are good reasons to decompose and expose these things in your API. While maybe not for Public consumption but certainly for Private.
It's my opinion that the way REST beats SOAP in the enterprise is that in almost all cases it's much quicker to build decomposed services. And then likewise composition of said services is also much easier.
Of course, it would be better if there was a Standard Poll Format to avoid the proliferation of custom formats that reduce code reuse, but alas, I don't think there is.
> A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...
If a book is added, the page=x resource is simply outdated and should be refreshed.
A better more "RESTful" approach might be:
The REST client would then be able to traverse the representation without making guesses at the URL, and if the end-point of '/authors:id' changes for whatever reason, the href would be updated accordingly.Pagination/large data-sets could be solved as well:
... and a bajillion other common RESTful API problems through better convention.I'd agree with the author that REST is misunderstood, but my opinion is that its misunderstood on the grounds that today's "REST" implementations are lame database serializations. The web has been doing this since the <a href/> tag was conceived, but for some reason, modern REST implementations left this out.