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

Getting hyper about hypermedia APIs

37signals.com

Post reply on HN
Print view View original

31–40 of 73 posts

Re: Getting hyper about hypermedia APIs

#31

Post by MatthewPhillips »

icebraining wrote: post #28

According to hypermedia lore, you will be able to willy nilly change your URLs without needing to update any clients. But that’s based on the huge assumption that every API call is going to go through the front door every time and navigate to the page they need. That’s just not how things work. This is missing forest for the trees. The point is not that you, the API implementor, will be able to change URLs willy nill…

> and tomorrow someone creates Blinkr, which implements the same API,

So the benefit of hypermedia apis is predicated on something happens that almost never ever happens?

Re: Getting hyper about hypermedia APIs

#32

Post by icebraining »

mjs wrote: post #10
AffableSpatula wrote: post #2

I wrote the spec for application/hal+json that got compared to WS-star , here's where I'm coming from: JSON doesn’t have links. Establishing some basic conventions for that makes complete sense. Defining those conventions is called a spec. Giving a payload that follows conventions a name also makes sense. Establishing that is called registering a media type identifier. It makes no sense to keep reinventing the linkin…

Are there any examples of what, for example, the Flickr or Twitter API would look like under hal+json? I'm struggling to see how application/hal+json would help me write a client to upload a photo. I imagine that with or without hal I'm ultimately going to POST the data to some endpoint. The question is, how do I figure out what endpoint to use? Without hal+json I need to read the API docs to discover that "/photos/"…

Hypermedia doesn't claim that you don't have to read the docs, that's a misconception. You do have to read and know how to parse the file formats.

The main advantage is that know that your application supports Twitter, it also supports every other service that uses the same file formats, since they can be shared, re-used and standardized. Obviously, two services can't use the same URLs, so if you hardcode them, you're locked in.

Re: Getting hyper about hypermedia APIs

#33

Post by steveklabnik »

necrodome wrote: post #29
steveklabnik wrote: post #23

Bias alert: I'm the newest Rails committer and one of the bigger proponents of Hypermedia APIs in the Ruby world. Anyway, many, many other companies _do_ find hypermedia principles to be useful. See Balanced Payments, for example: > Fun fact: our internal statistics show that client libraries that construct the uri receive roughly 2 orders of magnitude more 404 status codes from Balanced than clients which use the ur…

What are the best options to implement that for an API backend with Rails a javascript library/framework for the interface?

The current Rails Party Line is "Jbuilder + you don't need integration" https://twitter.com/dhh/status/281802247480958976 https://twitter.com/dhh/status/281802391316201472

Some members of the core team and I have started a "Rails API" project specifically to explore these possibilities, and to extract common patterns from the apps we build: http://github.com/rails-api

This will encompass hypermedia and non-hypermedia APIs, as well as SPAs with a Rails backend. Most of us are focusing on Rails 4 at the moment, and will start working hard on this post-Rails 4 release, but about 23,000 people have installed the main gem, and I know several running it in production already.

I personally feel the best option right now is "Rails API + ActiveModel::Serializers + Ember.js". But we want to encourage a multiplicity of options. Not all apps are identical.

Re: Getting hyper about hypermedia APIs

#34

Post by icebraining »

MatthewPhillips wrote: post #31
icebraining wrote: post #28

According to hypermedia lore, you will be able to willy nilly change your URLs without needing to update any clients. But that’s based on the huge assumption that every API call is going to go through the front door every time and navigate to the page they need. That’s just not how things work. This is missing forest for the trees. The point is not that you, the API implementor, will be able to change URLs willy nill…

> and tomorrow someone creates Blinkr, which implements the same API, So the benefit of hypermedia apis is predicated on something happens that almost never ever happens?

On the contrary; REST, of which hypermedia is a constraint, is an architectural style derived from the observation of a very successful implementation of just that.

It's called HTTP + HTML, and there are millions of services implementing it.

Re: Getting hyper about hypermedia APIs

#35

Post by nkohari »

gamache wrote: post #9
MattRogish wrote: post #4

Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s. "If we just use RDF triples to encode everything then machines can learn that apples are fruits and fruits are good for you, thus apples are good for you! Huzzah!" Then, Microsoft invented SOAP. "If we just have a WSDL that explains all of our API, then we can have automated methods to communicate between services! Prog…

What concerns me about Hypermedia APIs is that folks are using the same sorts of grandiose, architecture astronaut-y stuff that we got out of the last two failed revolutions. You owe it to yourself to read the HAL+JSON specification: http://stateless.co/hal_specification.html Anyone who considers a three-page spec like that astronautics probably has a low capacity for complex thought.

A hint: when trying to convince, it's not a great idea to passive-aggressively insult the other party. Since they're human too, they will probably just get pissed off and write you off as an asshole. Like what I'm doing right now.

Re: Getting hyper about hypermedia APIs

#36

Post by steveklabnik »

tlrobinson wrote: post #26
AffableSpatula wrote: post #2

I wrote the spec for application/hal+json that got compared to WS-star , here's where I'm coming from: JSON doesn’t have links. Establishing some basic conventions for that makes complete sense. Defining those conventions is called a spec. Giving a payload that follows conventions a name also makes sense. Establishing that is called registering a media type identifier. It makes no sense to keep reinventing the linkin…

"JSON doesn’t have links." JSON doesn't, but HTTP does. Why not use Link headers?

That's another option, yes.

Re: Getting hyper about hypermedia APIs

#37

Post by steveklabnik »

MattRogish wrote: post #4

Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s. "If we just use RDF triples to encode everything then machines can learn that apples are fruits and fruits are good for you, thus apples are good for you! Huzzah!" Then, Microsoft invented SOAP. "If we just have a WSDL that explains all of our API, then we can have automated methods to communicate between services! Prog…

I'm one of the biggest proponents of hypermedia (been speaking about it for the last 18~ months at conferences) and I think the semantic web is bullshit.

Re: Getting hyper about hypermedia APIs

#38

Post by habitue »

jashkenas wrote: post #17

One neat trick that I think is worth adding to the discussion: URL templates. Returning URL templates as part of your API response can give you the benefits of having a clean way to access sub-resources, without the headaches and bloat of having to enumerate every possible desired sub-URL. For example, in DocumentCloud, a document's canonical representation has a unique URL for the content of every page as plain text…

Just a nit, but the syntax for query arguments would be: "http://www.documentcloud.org/documents/21939/search.json{?q}"

Re: Getting hyper about hypermedia APIs

#39

Post by MatthewPhillips »

AffableSpatula wrote: post #30
tlrobinson wrote: post #26

Earlier quoted context omitted.

"JSON doesn’t have links." JSON doesn't, but HTTP does. Why not use Link headers?

Link header parsers are far less ubiquitous than json, and Link headers aren't very good for use cases like representing links that come from items in a collection, there are also issues relating to the maximum feasible size for HTTP headers and/or the header block as a whole. Link relations are useful for adding links to media types that can't support links (e.g. images, etc), and for layering protocols (e.g. Linked…

Would this be a better fit as part of an OPTIONS request?

OPTIONS /orders

  {
    "GET": {
      "description": "All the orders."
      "links": {
        "self": { "href": "/orders" },
        "next": { "href": "/orders?page=2" },
        "find": { "href": "/orders{?id}", "templated": true },
        "admin": [
          { "href": "/admins/2", "title": "Fred" },
          { "href": "/admins/5", "title": "Kate" }
        ]
      }
    }
  }

Re: Getting hyper about hypermedia APIs

#40

Post by MattRogish »

steveklabnik wrote: post #37
MattRogish wrote: post #4

Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s. "If we just use RDF triples to encode everything then machines can learn that apples are fruits and fruits are good for you, thus apples are good for you! Huzzah!" Then, Microsoft invented SOAP. "If we just have a WSDL that explains all of our API, then we can have automated methods to communicate between services! Prog…

I'm one of the biggest proponents of hypermedia (been speaking about it for the last 18~ months at conferences) and I think the semantic web is bullshit.

Hi Steve,

Thanks for the reply. I'm basing my interpretation off of your http://designinghypermediaapis.com site and the associated listserv, so either I'm misinterpreting it, or we have a difference of opinion as to the complexity and utility of the proposed solution(s).

My fear is we're redefining WSDL in JSON's clothing. Yes, adding hrefs to the API isn't complex -- but the code to actually do something with it is, and that's where my spidey sense starts tingling (having just spent a few weeks in Savon/SOAP/WSDL/WSSE hell).

Post reply on HN