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

41–50 of 59 posts

Re: The Future is Hypermedia APIs

#41

Post by laughinghan »

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…

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. [...] A few years later and that roar is gone. Bootstrap.css for everything, with class names that describe structure. [...] the absolute 180 without even a hint of the old battle cry in the air is startling.

I don't think a single advocate of semantic CSS class names has changed their mind and now says there are no problems with using Bootstrap presentational CSS class names in your HTML. Just yesterday, on the front page of Hacker News, there was an article about the pain caused by overuse of Boostrap's unsemantic CSS class names: http://blog.pamelafox.org/2012/12/a-tale-of-two-bootstraps-l...

I don't know why you ever thought people were "screaming" about it, but if you're hearing about it less than about Bootstrap now, it's definitely from different people.

There are objective benefits for maintainability by designing your HTTP APIs to be RESTful, just as there are objective benefits for maintainability by choosing your CSS class names to be semantic, and they have been espoused by the creators of HTTP and CSS since their creation. It is neither "mania" nor "crazy".

Your child-like conversation with an unhelpful strawman notwithstanding, it is true that in the real world, software architecture always has to balance long-term maintainability against short-term ease of implementation. That doesn't change the fact that semantic CSS class names and RESTful APIs improve maintainability, always have, always will, people always have said they do, and people always will say they do.

Re: The Future is Hypermedia APIs

#42

Post by steveklabnik »

jsankey wrote: post #40
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.

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 i…

> You're adding at least one request.

It's pretty trivial to have the client hit the root on startup, and then cache that and never make another call. API roots don't change very much.

> First, are there then multiple roots?

Nope. Here's an example of what I call the 'hypermedia proxy pattern' in Sinatra: https://gist.github.com/3172911

I based this off of this talk by Jon Moore: https://vimeo.com/20781278 and demo'd it at the end of this presentation: http://oredev.org/2012/sessions/designing-hypermedia-apis

Basically, you can fold elements of the collection up into the parent, and the client will automatically make less requests. Jon's presentation goes from 14 requests for the first iteration to 2 on the first hit, 1 every hit thereafter, with no changes to the client.

> when your data is hierarchical, it's nice for other reasons to reflect this in your URI structure.

Sure! So provide both: one 'deep link' or full collection in the root (or wherever) response, but also serve the data as a separate resource that's hierarchical. Best of both worlds.

Re: The Future is Hypermedia APIs

#43

Post by jsankey »

steveklabnik wrote: post #42
jsankey wrote: post #40

Earlier quoted context omitted.

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 i…

> You're adding at least one request. It's pretty trivial to have the client hit the root on startup, and then cache that and never make another call. API roots don't change very much. > First, are there then multiple roots? Nope. Here's an example of what I call the 'hypermedia proxy pattern' in Sinatra: https://gist.github.com/3172911 I based this off of this talk by Jon Moore: https://vimeo.com/20781278 and demo'd…

> It's pretty trivial to have the client hit the root on startup, and then cache that and never make another call. API roots don't change very much.

That's true and will work in most cases, but perhaps not when client sessions are short-lived.

> Basically, you can fold elements of the collection up into the parent, and the client will automatically make less requests.

Now it looks like my choices are to either fetch more data than I need, or make more requests than I need.

> Best of both worlds.

Well, both best and worst of both worlds. Each approach needs to stand up to cost-benefit analysis alone or I doubt it's worth maintaining both.

I do see advantages in these patterns, but I think some of them are more theoretical than practical, and I'll take the practical advantage I see today over the theoretical one I might need in the future.

Re: The Future is Hypermedia APIs

#44

Post by robconery »

I dunno. It seems like the future is arguing about Hypermedia. If the idea doesn't take hold ... is that our fault as developers? It reminds me of the OpenID hype - engineers solving a problem that doesn't exist or, worse yet, solving a future problem that has yet to materialize.

If the answer to this is "educate people" then that's the wrong answer. Or maybe it's the right answer if you're an IT type that loathes their users. I know I might sound crusty about all of this but how many years are we going to chase an idea that only a few people seem to understand?

Can we just admit it, right here, right now: all of this is academic. We should be focused on extracting patterns and practices that provide value and cycling on that.

The rest is noise.

Re: The Future is Hypermedia APIs

#45

Post by BerislavLopac »

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…

"The developers I was working with also had a lot of trouble with REST. I had to explain repeatedly what PUT, DELETE, GET and POST were (they weren't really familiar with HTTP at all), and that they weren't doing RPC calls."

You should try using the SQL analogy instead of RPC, as this is much closer to what a "traditional" developer might expect. With REST, one is not doing a procedure call, but one is querying to create/retrieve/update/delete data. Of course, there might be some procedures behind it, but to a client it's just a data query (just like SQL has stored procedures of its own).

Re: The Future is Hypermedia APIs

#46

Post by mjs »

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/

Oh! If that's the sort of thing we're talking about, then I'm all for it. The proponents of Hypermedia APIs have been saying a lot of vague things about how it will enable automated clients, and I assumed that the clients they had in mind would be able to do something useful with arbitrary APIs.

But it's clear from GitHub's API that it will do nothing of the sort: those link relations (and even concepts) are very much GitHub specific, and no machine will ever be able to figure out what to do with the them, what methods or media types the endpoints support, and so on.

(I'm not sure that it adds very much over a text document that that gives the relations and how to generate endpoints, but at least it's cheap to produce, and not actively harmful.)

Re: The Future is Hypermedia APIs

#47

Post by mjs »

steveklabnik wrote: post #18
mjs wrote: post #15

A few thoughts: * Mike Kelly (the author of the HAL spec) is not aiming for a universal API client http://news.ycombinator.com/item?id=4949357 (and also seems to be under the impression that no-one else is either). * A universal client seems impossible because APIs will typically need to use service-specific link relations for all "interesting" relations (e.g. product, author). You might be able to share generic link…

We already have a 'universal API client' called the browser. Therefore, implementing a NEW one isn't very interesting.

Sorry, I don't get what you're responding to. Browsers don't understand hypermedia APIs (or even HAL)--they only grok HTML.

Re: The Future is Hypermedia APIs

#48

Post by steveklabnik »

mjs wrote: post #47
steveklabnik wrote: post #18

Earlier quoted context omitted.

We already have a 'universal API client' called the browser. Therefore, implementing a NEW one isn't very interesting.

Sorry, I don't get what you're responding to. Browsers don't understand hypermedia APIs (or even HAL)--they only grok HTML.

> Browsers don't understand hypermedia APIs (or even HAL)--they only grok HTML.

HTML is a hypermedia media type. A server spits it out, the client (a browser) consumes it.

A browser is a generic hypermedia API client, for services that expose HTML.

Re: The Future is Hypermedia APIs

#49

Post by steveklabnik »

mjs wrote: post #46
steveklabnik wrote: post #36

Earlier quoted context omitted.

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

Oh! If that's the sort of thing we're talking about, then I'm all for it. The proponents of Hypermedia APIs have been saying a lot of vague things about how it will enable automated clients, and I assumed that the clients they had in mind would be able to do something useful with arbitrary APIs. But it's clear from GitHub's API that it will do nothing of the sort: those link relations (and even concepts) are very muc…

> The proponents of Hypermedia APIs have been saying a lot of vague things about how it will enable automated clients, and I assumed that the clients they had in mind would be able to do something useful with arbitrary APIs.

Consider a web browser, or an RSS reader. These are generic hypermedia clients that consumer standardized media types.

> But it's clear from GitHub's API that it will do nothing of the sort: those link relations (and even concepts) are very much GitHub specific, and no machine will ever be able to figure out what to do with the them, what methods or media types the endpoints support, and so on.

Right. We're not talking about AI, we're talking about generic re-usable components.

> (I'm not sure that it adds very much over a text document that that gives the relations and how to generate endpoints, but at least it's cheap to produce, and not actively harmful.)

The point is that by forcing you to define the communications protocol up front, you de-couple clients and servers. This means that they can evolve separately. Think about the RSS example: new versions of RSS clients can be made, and the servers don't need to be updated, and servers can update themselves and their responses and you don't need a new version of the client to handle it.

The other advantage is that if there are multiple services in the same product domain, and they use the same type, you get generic re-use of clients across services. Everyone spits out RSS, everyone consumes RSS.

Re: The Future is Hypermedia APIs

#50

Post by steveklabnik »

BerislavLopac wrote: post #45
notJim wrote: post #11

Earlier quoted context omitted.

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…

"The developers I was working with also had a lot of trouble with REST. I had to explain repeatedly what PUT, DELETE, GET and POST were (they weren't really familiar with HTTP at all), and that they weren't doing RPC calls." You should try using the SQL analogy instead of RPC, as this is much closer to what a "traditional" developer might expect. With REST, one is not doing a procedure call, but one is querying to cr…

HTTP verbs do not map exactly to CRUD.
Post reply on HN