How I learned to stop worrying and love REST | Hacker News Reader

How I learned to stop worrying and love REST

mikemayo.org

81 pointsjohns32 comments

This is probably my number one criticism of most "REST" APIs out there - they are horribly non self-documenting, and the effort required to make them self-documenting is really fairly trivial:

1. Ensure that you have a URI to the resource in question every single time you reference an ID somewhere (in collections, when referencing resources from another resource)

2. Make the root of your application document all the collections available and their respective URIs.

3. Include paging URIs as mentioned in the article.

4. If a resource has nested collections, include URIs to them in your JSON representation of the resource.

Boom! You now have a REST API better than 99% of what's on the web today.

and this is what i was talking about!

Yes, what you describe is true. We also had a good discussion a few days ago about scenarios where REST doesn't seem to work well. The specific problem is when things start getting too chatty. Its very difficult to expose a flexible (fine-grained) REST API and at the same time give you all the data you need in the least amount of calls. It takes quite a bit of work up front to figure out what your model is going to be and figuring out if that model will work for most of your consumers. Getting the 'pattern' down as you described is half the battle.

http://news.ycombinator.com/item?id=3538585

http://news.ycombinator.com/item?id=3538134

What is the HATEOS compliant way of accepting parameters? E.g. for the pagination example, you might want to let the consumer specify number of entries pr. page, or you might want to accept a search-term or limit by period.

An HTML form could be one way of doing this. As long as the API complies with the form it sends out.

However, getting a client to automatically understand this is a little harder.

You could approximate a form in JSON, which would be similar in structure to its HTML counterpart.

This is such a fundamental problem that I am surprised that there is not a definitive answer.

The HTML form tag; also expressed more directly as URL templates. The server provides the parameterized template, and the client fills in the params to access the resource.

Query parameters create hyperlink templates.

    href="foo/bar/?baz=x"

is really a way for generating a set of hyperlinks that range over whatever domain x comes from and the client should feel free to plug in any valid value for x. You can even indicate the domain of x by returning a 405 in the case of an invalid value (although it would be nice to have a standard way of indicating the domain beforehand)

For instance, if there are 10 pages then x ranges over [1-10]. If the client request ?page = 11 then we'd return a 405 error indicating that the only valid values are [1-10].

I find URL templates smelly. Once you stick a place holder in the URL, it's no longer a valid URL - it's something that requires custom mangling before it can be passed along.

In your example, I need to know that the x is something that requires replacement. How is that fundamentally different from just putting in your documentation (and, in the 405 if not passed) "this resources takes query param baz" - which is not HATEOS?

Also, this doesn't cover the case of optional parameters. Specifying optionality in a template is horrible (something like "bar/?baz=x[&ogle=y]" to borrow the pattern from man pages), and specifying individual URLs for each combination of parameters is impractical for more than a few.

> I find URL templates smelly. Once you stick a place holder in the URL, it's no longer a valid URL - it's something that requires custom mangling before it can be passed along.

This is why a standard has been drafted for this particular problem, the mangling becomes standard and predictable rather than customized to each use case.

http://tools.ietf.org/html/draft-gregorio-uritemplate-08

It may smell, but clients that uses URL templates may still be RESTful. For this to work, 1.) the server must decorate the response with the proper resource type identifier, 2.) the client must be able to understand the resource type, and 3.) the resource type spec must specify how the clients should treat URL templates.

Web browsers are REST clients that understand the HTML resource type. They, too, can generate URLs. For example, in HTML, you can specify a URL template with the following code:

    <form action="foo/bar/" method="get">
      <input name="baz" type="text">
      <input type="submit" value="Submit" />
    </form>

Input tags with type="text" are, by default, optional. Newer HTML spec allows you to annotate input tags with the "required" attribute, which allows you to specify them as required.

You can define your custom resource type to do the same if you want:

    { "form": { "action": "foo/bar/",
                "method": "GET",
                "fields": [ { "name" : "baz" } ]
    }

You can make the above example a lot leaner by trimming out features you don't care about. It's all up to how you design the spec of your resource type.

I think you should have a pagination resource that understands a resource and returns a paginated URL.

it would accept parameters. I think having a template requires the client to understand a format other than hypertext.

According to Steve Klabnik, this can be accomplished via GET forms and using query templates: http://amundsen.com/media-types/collection/format/#query-tem...

There is actually a HTTP header (Range) that can be used for this. Works well in APIs but you can't do it with browsers, which is unfortunate.

Can you not set custom headers in browsers?

You can do it with AJAX requests, but not with links or regular forms (as far as I am aware... I'd love to hear otherwise)

Should a REST API ever be expose by a form or link?

The web is basically a REST API, no? (I'm being a bit facetious.)

Disclaimer: I do not want to steal the author's page views, but I could hardly read this article, due to the white shadow in the Text. Here is a more readable view: http://rdit.in/5c

Frankly that shadow has always bothered me too. I've changed it up now, hopefully that's a little easier on the eyes.

In Chrome I do right-click, inspect element. Then I CSS the shadow away :)

Just because you can, doesn't mean you should (have to).

I suggest you try out Evernote Clearly http://www.evernote.com/clearly/ . It comes with a browser extension, using which you can convert a blurb of text that is difficult to read into an easily readable one.

Thanks for the suggestion. There are others as well: http://www.readability.com/bookmarklets http://www.instapaper.com/m

Clear Read is my own take on this though.

i'm suprised using something like mod_rewrite to transform the query parameters into something that rails could cache was not mentioned. it's a cheap way to use the url structure you want after the fact. the next update the app can then use the new structure and the mod_rewrite rules will be there to support the old api until almost everyone has upgraded to the new app. this allows one to switch an api to being more restful in a graceful way.

good to see a hometown guy on the frontpage of HN ... I feel proud (for once) to be from Louisiana :P

I hate when people try tell me REST isnt the way to go. I guess if you're an out-dated organization with a lot of time (and money) on your hands, you could stuff around with something else...but why would you in this world as a startup do anything else?

Nice article, i think the world needs a very basic "this is how you use REST" bullet point style blog post somewhere. This lesson would be 1 of those bullet points if i were writing it.

>why would you in this world as a startup do anything else?

Because the tech's immature and irrelevant to your core competency? The paragraph at the end of the HATEOAS page sums it up pretty well for me - and seems to be struggling to make the case for the benefits of "full REST". I despise the enterprisey verbosity of SOAP et al, but given the choice between an inefficient but well understood standard with good tooling support and the new hotness that no-one quite understands properly yet...

Yeah i guess you're right, i too get quiet frustrated by how verbose SOAP is and that's the true reason as to why i've personally avoided.

Having worked fairly extensively with the Facebook API in recent years i've just come used to dealing with REST API's (and honestly while they do a half decent job, it has a lot of shortcomings)

I just find the time to get a REST API up and running is very short, and for that reason it tends to be my choice. Not saying its the right one however :P

Someone asked for some Dos and Don'ts here and started a nice list: http://news.ycombinator.com/item?id=3538392

Have you actually ever been a consumer of an extensive, pure REST API? At the point in time in which you are required to make a couple hundred requests in a single page in order to build something useful you'll start to wonder why it's touted so much.

Unless, of course, the company maintaining the API has the resources to have almost all requests cached and a responsible data design to facilitate accurate ETAG matching. If not... well you are going to be at the whim of their server architecture.

Even then, that's an incredible amount of calls to make just to display some information.

Reply on news.ycombinator.com