How I learned to stop worrying and love REST

http://mikemayo.org/2012/how-i-learned-to-stop-worrying-and-love-rest

by johns • 14 years ago

81 31 14 years ago

mmackh2• 14 years ago

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

gotmayonase2• 14 years ago

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

NanoWar• 14 years ago

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

scoot• 14 years ago

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

shreyas-satish• 14 years ago

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.

mmackh2• 14 years ago

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.

ryanbrunner• 14 years ago

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.

verelo3• 14 years ago

and this is what i was talking about!

vyrotek2• 14 years ago

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

verelo3• 14 years ago

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.

lmm• 14 years ago

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

verelo3• 14 years ago

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

vyrotek2• 14 years ago

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

methodin• 14 years ago

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.

zbruhnke• 14 years ago

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

mseebach2• 14 years ago

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.

scott_w• 14 years ago

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.

sopooneo• 14 years ago

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

justinludwig• 14 years ago

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.

noblethrasher• 14 years ago

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

mseebach2• 14 years ago

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.

mahmoudimus• 14 years ago

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.

gotmayonase2• 14 years ago

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

bodhi3• 14 years ago

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.

alexchamberlain2• 14 years ago

Can you not set custom headers in browsers?

mikeytown2• 14 years ago

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.

How I learned to stop worrying and love REST

Related Stories