Getting hyper about hypermedia APIs • Hacker News Board

Re: Getting hyper about hypermedia APIs

#71

Post by AffableSpatula » Fri, Dec 21, 2012, 9:16 AM UTC

mjs wrote: post #64

AffableSpatula wrote: post #45

Earlier quoted context omitted.

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? http://stateless.co/hal_specification.html

I have no idea why you would conclude that from that sentence. HTML allows browsers, the same way that HAL allows generic libraries. I'm struggling to understand why this is controversial, there are already 16+ examples of generic HAL libraries across a bunch of different languages.

Re: Getting hyper about hypermedia APIs

#72

Post by programminggeek » Fri, Dec 21, 2012, 4:41 PM UTC

icebraining wrote: post #24

programminggeek wrote: post #8

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

I think that assumes some serious hand waving on the part of both your app and the api's. Assuming that just pointing at the root of another API is going to mean your app will magically behave properly using both API's is making a lot of assumptions either in your app about how the API's work. For example, say one API calls a delete call "delete", another calls it "remove", another calls it "obliterate", and at the same time one API takes an id on that method as input, another takes an email address, another takes a username. In that scenario your app might be written to remove something based off an id and when you switch API's the new one expects you to obliterate based on username. Hypermedia doesn't save you there.

I'm all for pluggable protocols and standards, but Hypermedia links in your API don't magically get you there. They might help, but no more than a standard spec with standard URL patterns would.

Re: Getting hyper about hypermedia APIs

#73

Post by msbarnett » Fri, Dec 21, 2012, 9:31 PM UTC

gamache wrote: post #70

msbarnett wrote: post #63

Earlier quoted context omitted.

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

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

All I can say to this is that we have vastly different approaches to engineering.

Features are debt. Adding features you don't need now and will probably never need in service of some kind of ideological purity ("doing it right") is the worst kind of deficit spending.

I've done my time in big enterprise vast complex interlocking highly abstracted development. For every 1 time prematurely optimizing for flexibility happened to pay off, it resulted in onerous development and maintenance overhead for no benefit 9 other times. Do the simplest thing that works. If you don't need it now, assume you ain't gonna need it and only build it if and when you have a pressing need for it. To me, these are the very core of sound, reliable engineering.