Hacker News Reader

Comment by paul_odin | Hacker News Reader

Is there a list of Hypermedia-esque APIs in use today (apart from sitemap)? I can find lots of explanations of the concept but it's hard to find examples.

The closest I can think of is the way some APIs handle pagination (GitHub and Recurly for example) by using Link: rel=next/prev/start headers rather than through GET parameters, which in principle would allow a generic REST client to iterate through results on its own.

View on HN

Like steveklabnik mentioned, take a look at the Balanced API, here's an example you can run yourself using a test marketplace:

    curl https://api.balancedpayments.com/v1/marketplaces/TEST-MP6IEymJ6ynwnSoqJQnUTacN -u 7b7a51ccb10c11e19c0a026ba7e239a9:

To keep this thread free of tons of code samples I've included the result @ https://gist.github.com/4350290

You can see in our python client how we then parse - https://github.com/balanced/balanced-python/blob/master/bala... - the result of this which then consumes these URIs and turns them into dynamic resources attached to whatever object you're looking at.

This means you can do this:

    debit = balanced.Debit.find(uri)
    debit.account.cards.all()  # get a list of all cards associated with the account that created this debit

And the client does not have to know anything about the fact that debits have an account property, or that accounts have a cards resource underneath them.

I think we should probably write about https://github.com/bninja/wac and how our Balanced Python client influences it. Gone are the days when your internal services need to sync on some kind of schema.

We make changes to our internal services all the time and HATEOAS allows us to ensure our services are properly functioning without breaking contractual API obligations.

I can see why most developers resist the urge to try hypermedia APIs and it's honestly because the tooling to build services and clients just aren't there.

This is why I'm a big fan of the https://github.com/rails-api/rails-api project. It's essentially accepting this deficiency, has some brilliant minds behind it and as a consequence, I'm sure the tooling to be built around it will be amazing; it's definitely one to follow.

Some more resources:

* https://github.com/rails-api/rails-api

* http://django-rest-framework.org/

GitHub does it for more than pagination: http://developer.github.com/v3/pulls/

Please see my comment here: http://news.ycombinator.com/item?id=4949311

Also, Balanced (YC W11): https://www.balancedpayments.com/docs/overview#storing-the-u...

$ curl https://api.github.com

We're experimenting with more :)

<3 <3 <3.

I really need to buy you a beer sometime.

That's cool :) I agree with steveklabnik, I want to see what Balanced can do to learn from Github's experiments in hypermedia APIs

So sexy.

What are the advantages/disadvantages of serializing links in the body JSON (i.e. HAL) vs. using the Link header?

This is a good question, and the answer is philosophical purity and pragmatism. Philosophically, some people believe that this information should be encapsulated in the HTTP response body, while others believe that they should be able to leverage all of the parts of the HTTP spec including the response headers. Pragmatically, certain environments make it harder or easier to access certain parts of request and response objects, but the lowest common denominator is the body content.

Reply on news.ycombinator.com