Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Future is Hypermedia APIs

emergentone.com

Post reply on HN
Print view View original

31–40 of 59 posts

Re: The Future is Hypermedia APIs

#31

Post by mahmoudimus »

mjallday wrote: post #28
paul_odin wrote: post #7

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…

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://git…

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/

Re: The Future is Hypermedia APIs

#32

Post by dreamdu5t »

technoweenie wrote: post #22
steveklabnik wrote: post #9

Earlier quoted context omitted.

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 :)

So sexy.

Re: The Future is Hypermedia APIs

#33

Post by sopooneo »

I am having deja-vu. When I was just starting, everyone screamed about pure "semantic" markup and how all css class names should describe what was contained in a node, and have nothing to do with how it was presented. People bent over backwards to comply. I couldn't make it work, but assumed I was just far behind the curve. A few years later and that roar is gone. Bootstrap.css for everything, with class names that describe structure. I can't say I'm hurt by this as it is what I had resorted to all along. But the absolute 180 without even a hint of the old battle cry in the air is startling.

I feel like that is again happening here. I can not image how fully compliant REST api's would work in the real world. And when I ask for an example? Twitter, check the Twitter API! But no, that breaks the rules all over the place in the name of practicality. Oh yeah? You want a real example? How about the whole web? The whole web is your example!. That example is so far outside of instructive or helpful I don't even know where to start. I stand agape, unable to even speak. The way clients access my blog system should be based on the whole web? Even though it itself is on the web?

I'm done chasing prophets. In five years I do not believe this REST mania will exist anymore, and not because it is so ubiquitous as to go unstated. It will have died or changed drastically in the name of actually working. Bootstrap.rest. Either I am too dumb, or the movement is crazy, or both. But either way, I'm done trying to make things in a way I don't understand. The great and holy can thump their Fielding Bibles with faith that they will be taken home soon. Me, I've given up on salvation, and find the road to hell a much less exhausting one.

Re: The Future is Hypermedia APIs

#34

Post by jsankey »

“Proper” use of a REST or hypermedia API generally requires you only ever initiate communications with the API from the root (https://my.api.example/ versus https://my.api.example/some/other/url). From there, every response from the API will then contains links to other resources, often with a relation to explain how each resource relates to the next. In this way, you never guess a URL - you are always given it.

Speaking from practical experience using an API like this: it can result in a lot of extra round trips to get to your final destination. The indirection is nice purity-wise, but in practice do you really want to make 3-4 times the round trips to the server for every API interaction? Especially when you might be on a mobile network? All for the sake of flexibility you may never need?

I'd say supporting the discoverability for learning, and consistency etc is nice. But in practice concerns like this (and the DHH example, and others already in comments here) will crop up and clients will start building their own direct URLs. So the idea that you'll be able to change the URL structure without affecting clients is a pipe dream.

Re: The Future is Hypermedia APIs

#35

Post by steveklabnik »

jsankey wrote: post #34

“Proper” use of a REST or hypermedia API generally requires you only ever initiate communications with the API from the root ( https://my.api.example/ versus https://my.api.example/some/other/url ). From there, every response from the API will then contains links to other resources, often with a relation to explain how each resource relates to the next. In this way, you never guess a URL - you are always given it. Sp…

> it can result in a lot of extra round trips to get to your final destination.

You can usually get around this. Many people make their resources have too much hierarchy; there's nothing inherently unRESTful about having a flat one.

You should _not_ be having 3-4 round trips for every API interaction. Each request is an interaction. Hypermedia APIs expose a workflow, not a data model.

Re: The Future is Hypermedia APIs

#36

Post by steveklabnik »

sopooneo wrote: post #33

I am having deja-vu. When I was just starting, everyone screamed about pure "semantic" markup and how all css class names should describe what was contained in a node, and have nothing to do with how it was presented. People bent over backwards to comply. I couldn't make it work, but assumed I was just far behind the curve. A few years later and that roar is gone. Bootstrap.css for everything, with class names that d…

> I can not image how fully compliant REST api's would work in the real world.

Have you ever used GitHub's API?

    $ curl https://api.github.com/

Re: The Future is Hypermedia APIs

#37

Post by Milagre »

steveklabnik wrote: post #35
jsankey wrote: post #34

“Proper” use of a REST or hypermedia API generally requires you only ever initiate communications with the API from the root ( https://my.api.example/ versus https://my.api.example/some/other/url ). From there, every response from the API will then contains links to other resources, often with a relation to explain how each resource relates to the next. In this way, you never guess a URL - you are always given it. Sp…

> it can result in a lot of extra round trips to get to your final destination. You can usually get around this. Many people make their resources have too much hierarchy; there's nothing inherently unRESTful about having a flat one. You should _not_ be having 3-4 round trips for every API interaction. Each request is an interaction. Hypermedia APIs expose a workflow, not a data model.

> Hypermedia APIs expose a workflow, not a data model.

I would say this is true of REST APIs. Not necessarily hypermedia APIs. An API that directly exposed a graph database as an HTTP-based API using hypertext/links within resources would still need to be classified as a hypermedia API, but would fail to adhere to the HATEOAS principle.

Edit: More specifically - a graph database that exposed itself with links for every edge and a resource for every node.

Re: The Future is Hypermedia APIs

#38

Post by steveklabnik »

Milagre wrote: post #37
steveklabnik wrote: post #35

Earlier quoted context omitted.

> it can result in a lot of extra round trips to get to your final destination. You can usually get around this. Many people make their resources have too much hierarchy; there's nothing inherently unRESTful about having a flat one. You should _not_ be having 3-4 round trips for every API interaction. Each request is an interaction. Hypermedia APIs expose a workflow, not a data model.

> Hypermedia APIs expose a workflow, not a data model. I would say this is true of REST APIs. Not necessarily hypermedia APIs. An API that directly exposed a graph database as an HTTP-based API using hypertext/links within resources would still need to be classified as a hypermedia API, but would fail to adhere to the HATEOAS principle. Edit: More specifically - a graph database that exposed itself with links for eve…

I personally draw a distinction between "Hypermedia APIs" and 'hypermedia APIs.' The former is 'orthodox REST' and the latter is 'an API that serves up hypermedia.'

Re: The Future is Hypermedia APIs

#39

Post by sopooneo »

steveklabnik wrote: post #36
sopooneo wrote: post #33

I am having deja-vu. When I was just starting, everyone screamed about pure "semantic" markup and how all css class names should describe what was contained in a node, and have nothing to do with how it was presented. People bent over backwards to comply. I couldn't make it work, but assumed I was just far behind the curve. A few years later and that roar is gone. Bootstrap.css for everything, with class names that d…

> I can not image how fully compliant REST api's would work in the real world. Have you ever used GitHub's API? $ curl https://api.github.com/

I have not. But I will play with it. Thank you for the suggestion.

Re: The Future is Hypermedia APIs

#40

Post by jsankey »

steveklabnik wrote: post #35
jsankey wrote: post #34

“Proper” use of a REST or hypermedia API generally requires you only ever initiate communications with the API from the root ( https://my.api.example/ versus https://my.api.example/some/other/url ). From there, every response from the API will then contains links to other resources, often with a relation to explain how each resource relates to the next. In this way, you never guess a URL - you are always given it. Sp…

> it can result in a lot of extra round trips to get to your final destination. You can usually get around this. Many people make their resources have too much hierarchy; there's nothing inherently unRESTful about having a flat one. You should _not_ be having 3-4 round trips for every API interaction. Each request is an interaction. Hypermedia APIs expose a workflow, not a data model.

First, are there then multiple roots? If so, you've already sacrificed one level of indirection, moving knowledge to the clients. If not, you're adding at least one request.

Secondly, when your data is hierarchical, it's nice for other reasons to reflect this in your URI structure. It's intuitive (and thus discoverable in its own way) and can make for human-friendly URLs (especially when your datatypes have natural identifiers).

Post reply on HN