Aren't links also proper global IDs, allowing us to address objects cross-service ?
Yep. URIs are 'universal.'
Getting hyper about hypermedia APIs
61–70 of 73 posts
Re: Getting hyper about hypermedia APIs
#62DHH's API philosophy (send simple JSON serializations over the wire, mostly from the server to the browser) got him through the 2000's OK, but the longer he argues against hypermedia, the less relevant Rails becomes for API design. These are not particularly good arguments he puts forth here. I believe they are in response to Mike Kelly (designer of the HAL+JSON hypermedia format) and his recent post: http://blog.sta…
These are not particularly good arguments he puts forth here Would you care to explain why you think they're not particularly good? You're blaming DHH of being "hand wavy" but I don't see any more depth from your comment.
I spell out some concrete advantages to hypermedia APIs elsewhere in these comments. http://news.ycombinator.com/item?id=4948652
But to specifically address DHH's arguments from the article:
* Enabling Discovery is a strawman argument; no one expects an API to use / as its only documentation (at least no one expects it of a good API).
* Standardizing API Clients is also a strawman; no one expects to have one generic client magically make sense of any API.
* Comparing HAL to WS-* in order to paint it as committee-driven standards bloat is not fair to HAL, which is an admirably tight and cogent specification.
Re: Getting hyper about hypermedia APIs
#63Earlier quoted context omitted.
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/"…
You still need to know the meaning of each link relation, that is true. When hypermedia advocates gloss over this, or imply that clients will just magically know what to do with all the data and links coming from the API entry point, it annoys me. It's dishonest. But what you gain from link relations is worth advocating for: * Link relations can be standardized across APIs. This opens the door for clients to infer fu…
> As long as the 'photos' link relation does not change, it can point to whatever URL it wants, and that URL or URL structure can change over time without damage to the client.
So here's where my skepticism kicks in:
How often are you really expecting your URL structure to change, in practice? And when the URL structure does change, what percentage of the time does the change in URL structure also coincide with a change in semantics that clients logic will need to be changed to take into account?
In my experience the answer to those questions is 1) Very rarely. 2) Nearly always.
Re: Getting hyper about hypermedia APIs
#64Earlier quoted context omitted.
Ah, maybe I misunderstand what you're trying to do. I thought Hal was trying to make it possible to write clients that can buy from Amazon or eBay without knowing anything about the specifics of either. But actually what it's attempting is a sort of machine-assisted documentation system? (Since you still need a human to read the docs to find out how to signup, place orders, and so on.) I can see how that might work,…
That is one of the benefits that relates to documentation, which is the part of your comment I was responding too. The larger goal of hal+json is to establish some conventions for linking that allow the development of generic tools for doing hypermedia. Not to create magical machine clients that can interact with any random API you point them at. Nobody made that argument so I don't know why DHH addressed it in his p…
Well ... the spec does say "HAL is a bit like HTML for machines, in that it is generic and designed to drive many different types of application." To me (and perhaps DHH), that suggests that it's designed to be used to create clever clients. Perhaps you can clarify this point in a future edition of the draft?
Re: Getting hyper about hypermedia APIs
#65Earlier quoted context omitted.
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'r…
I can imagine Twitter publishing a application/tweet+json media type or similar, and clients and servers either supporting this or not (and exchanging Accept headers and 415 Unsupported Media Types as they go), but I don't get what that has to do with HAL.
For example, the "comments" link relation in
http://developer.github.com/v3/pulls/
points to
https://api.github.com/octocat/Hello-World/issues/1/comments
but no-where in the document does it say what media types that endpoint will accept.
Re: Getting hyper about hypermedia APIs
#66Aren't links also proper global IDs, allowing us to address objects cross-service ?
Yep. URIs are 'universal.'
I feel there is a lot of noise around IDs as URIs yet I've seen nobody (I may not have looked deep enought) talk about their main benefit as I perceive it, which is putting resources into the perspective of a global namespace. Thus allowing a service to reference resources provided by another service. This to me, looks like a practical revolution. We may at last have our contacts served by one entity, our statuses by another, our shared files by still another, and yet all of them could be handled as one distributed API.
The code glueing the whole to produce, say, a distributed facebook-like app, would still have to know the specifics of each provider (before standards emerge), but it would effectively break the isolation and allow us to composite services much more easily.
Where am I missing the point ?
Re: Getting hyper about hypermedia APIs
#67hypermedia APIs mean that our API's basically become web pages and every client should act like a browser. That's great if you want... a browser app. If you want to just expose data to let people build interesting things with it, hyperlinks in your api are a bit silly. They might be nice if you want someone to write a browser for your api, I don't see where else it would be awesome. Maybe if you want a web crawler to…
So you could write an app against the API of some service, then a competitor of that service comes and implements the same API, and so you want to switch. What should you do? Replace every URL? What if you want to support both (say, Twitter and Identi.ca)? Should you implement a map from codename ⇒ url? Now what if you want to support every possible implementation , even if you - the developer - don't know about them…
Both service will still not have the same resources behind the same IDs, even though they would provide the same services behind the same path. What you would have to do is use the same code to interact with two endpoints differing only by their domain. You could then use the resources delivered by both (statuses in you exemple) in one big merged list, each status still having in its data a pointer (URL) to the profile info of the author on the right service.
[Edit: I didn't get your point right away. So I guess we agree. It's a bit late here, I guess I'm off to bed !]
Re: Getting hyper about hypermedia APIs
#68Earlier quoted context omitted.
Yep. URIs are 'universal.'
I feel there is a lot of noise around IDs as URIs yet I've seen nobody (I may not have looked deep enought) talk about their main benefit as I perceive it, which is putting resources into the perspective of a global namespace. Thus allowing a service to reference resources provided by another service. This to me, looks like a practical revolution. We may at last have our contacts served by one entity, our statuses by…
> their main benefit as I perceive it, which is putting resources into the perspective of a global namespace.
Sometimes people do. I mentioned this problem in my talk at Øredev this year: http://oredev.org/2012/sessions/designing-hypermedia-apis
> Where am I missing the point ?
Well, you're on HN: everyone wants to control everything. Startups don't 'win' by playing nicely with each other, they drive their competitors out of business.
Re: Getting hyper about hypermedia APIs
#69hypermedia APIs mean that our API's basically become web pages and every client should act like a browser. That's great if you want... a browser app. If you want to just expose data to let people build interesting things with it, hyperlinks in your api are a bit silly. They might be nice if you want someone to write a browser for your api, I don't see where else it would be awesome. Maybe if you want a web crawler to…
So you could write an app against the API of some service, then a competitor of that service comes and implements the same API, and so you want to switch. What should you do? Replace every URL? What if you want to support both (say, Twitter and Identi.ca)? Should you implement a map from codename ⇒ url? Now what if you want to support every possible implementation , even if you - the developer - don't know about them…
Does this ever actually happen? What new web service has unveiled itself and implemented a competitors REST API?
Re: Getting hyper about hypermedia APIs
#70Earlier quoted context omitted.
You still need to know the meaning of each link relation, that is true. When hypermedia advocates gloss over this, or imply that clients will just magically know what to do with all the data and links coming from the API entry point, it annoys me. It's dishonest. But what you gain from link relations is worth advocating for: * Link relations can be standardized across APIs. This opens the door for clients to infer fu…
> As long as the 'photos' link relation does not change, it can point to whatever URL it wants, and that URL or URL structure can change over time without damage to the client. So here's where my skepticism kicks in: How often are you really expecting your URL structure to change, in practice? And when the URL structure does change, what percentage of the time does the change in URL structure also coincide with a cha…
You're preaching for YAGNI, which is a philosophy that's more good than bad, for sure.
I am lamenting that doing hypermedia APIs properly isn't the default in Rails. I call out Rails because its massive appeal (to which I am no stranger) is doing It right by default, all over the place for the common case.
That obviates YAGNI, because it implies no extra cost incurred for doing it right. I'd rather enable It rather than assume I ain't gonna need It, all things being equal.
That said, I have worked in companies large enough that the interlocking pieces are pretty far removed, yet expected to interoperate fully. Having and using link relations could have saved us a couple of headaches. I am hopeful the Rails-api project might approach this with more.... maturity?