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

21–30 of 59 posts

Re: The Future is Hypermedia APIs

#21

Post by Milagre »

thibauts wrote: post #16
Milagre wrote: post #10

Earlier quoted context omitted.

> Apart from parsing, I am the API client in this instance. I'm the one making decisions from understanding what services are about. Your browser parses, yes, but then it goes and fetches images, css, javascript, iframes, etc. Following the analogy, these are 'api calls'. It knows to make these calls because the HTML defined the links, and for the HTML to be rendered the contents of the links are required. I maintain…

Sure css, js etc are fetched, but this is hard-coded behaviour, there is nothing dynamic or discovered about it. Or I fail to understand it. This may well be the problem then, as we can see here and elsewhere. Many people like me don't understand. The claims are too vague. We need real-world exemples of how this can be applied with clear benefits. Mere transposition of the hypertext qualities to a medium intended for…

> Sure css, js etc are fetched, but this is hard-coded behaviour, there is nothing dynamic or discovered about it. Or I fail to understand it.

It grabs the links from the content of the document it retrieved, using the rules of HTMLs structure to find them. That's both dynamic and discovered.

Re: The Future is Hypermedia APIs

#22

Post by technoweenie »

steveklabnik wrote: post #9
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…

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

Re: The Future is Hypermedia APIs

#23

Post by technoweenie »

notJim wrote: post #4

The HATEOAS wonks are crazy, IMO. Most people who consume your API will have no idea what HATEOAS is and they sure as hell won't care. What will they care about? The URL to hit to get the data they want. They will hardcode that URL in their app, too, so expect any changes to it to require a great deal of fanfare to re-educate your users. In theory, the URN solution could work, but it's far more complex and requires m…

> I drank the HATEOAS Kool-Aid when I first learned about REST too, and then I built a beautiful API that used it. What did the developers ask for? A list of URLs.

Maybe you should've built them a client too? https://www.braintreepayments.com/braintrust/when-rest-isnt-...

I've heard great things from people updating their API clients to use our new hypermedia stuff. So we're pushing forward with our hypermedia experiments at GitHub. People are still free to optimize for speed (reduce the number of HTTP calls in environments where it really matters) or even development speed (hardcoding a few API calls instead of dropping in a full client library) if they like.

Re: The Future is Hypermedia APIs

#24

Post by pdonis »

Milagre wrote: post #20
pdonis wrote: post #17

I'm confused about something. The author's "simple and easy solution" to the problem of people saving API URLs is to have a "bookmark relation" link; but all that means is assigning a unique, permanent name to the resource so people can find it again. Why wouldn't you just design your API so the API URL is that unique, permanent name? The "bookmark" link "identifier" ends up being a URL anyway; why not make it the AP…

This is a fair point! Mostly, I think that would produce an ugly API. The reason I've been leaning towards that solution is that it assigns the responsibility of locating any other resource, in one request, with full backwards compatibility, to exactly one location, freeing other locations to change in a more fluid and graceful way without the cruft. Edit: Oh and because other URLs can have the context of their paren…

Mostly, I think that would produce an ugly API.

I don't see why the API would have to be ugly. The examples of "bookmark" link URLs given in the article are perhaps ugly (using query strings, etc.), but there's no reason why such URLs couldn't be "nice" ones. The article talks about things like "what if I want a URL structure like /User/projects/5 instead of /projects/5?", but that's a red herring: you could just as easily say "what if I want a bookmark query string that looks like ?user=User&project=5 instead of ?project=5?".

The bottom line is that as soon as you have a public API, you have identifiers that can't be easily changed because people need to be able to bookmark them; and those identifiers can't be too ugly because they are visible to users. So they should work OK as API URLs.

Re: The Future is Hypermedia APIs

#25

Post by steveklabnik »

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

I really need to buy you a beer sometime.

Re: The Future is Hypermedia APIs

#26

Post by gcampbell »

steveklabnik wrote: post #9
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…

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

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

Re: The Future is Hypermedia APIs

#27

Post by politician »

notJim wrote: post #11
steveklabnik wrote: post #5

Earlier quoted context omitted.

> Most people who consume your API will have no idea what HATEOAS is and they sure as hell won't care. What will they care about? The URL to hit to get the data they want. A few years ago, before Rails made "REST" popular, this exact same statement was made. "Nobody is going to want to learn about PUT and DELETE. They just want to do everything over POST." > They will hardcode that URL in their app, too, This is an e…

You might be right, as you've clearly thought about this more than I have. I have a couple of thoughts though. > A few years ago, before Rails made "REST" popular, this exact same statement was made. "Nobody is going to want to learn about PUT and DELETE. They just want to do everything over POST." > This is an education problem. We're still in the early days of this stuff. The developers I was working with also had…

On the client API issues, one of the criticisms of both REST and RPC APIs I've heard several times on HN is that consumers of APIs, regardless of the technology approach, fail to get it right (cf TLS). Moreover, the best remedy is to build and ship your own client libraries for as many platforms as possible.

Re: The Future is Hypermedia APIs

#28

Post by mjallday »

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

Re: The Future is Hypermedia APIs

#29

Post by politician »

gcampbell wrote: post #26
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...

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.

Re: The Future is Hypermedia APIs

#30

Post by mahmoudimus »

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

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