Real-life hypermedia API examples ?

[RDahl]

Hello everyone,

I'm new on this channel (and kinda new in general to the API world), and very interested about hypermedia APIs. I got a couple questions for you :

- Do you know any example of real-life ( = production, real business case) and idealy open-source hypermedia APIs that you know of ?

I keep searching but I tend to only find not-open-source APIs, or APIs that tend to be a little too simple to be really convincing : I love Maze+XML from Mike Amundsen and also his Tasks API example for his book RESTful API Clients, but those 2 cases seem a little too simple for me. Any other example ?

The objections I get the most when I talk about hypermedia are the following :
- JSON is widely used because it is easily readable ; but adding all thoses extra fields to my responses bloats them, especially with verbose formats such as Collection+JSON. If you add that to the fact that client developpers aren't used to these formats, don't you think we risk losing clients, that would prefer a "traditionnal level-2" API ?
On the other hand, using a not-so-bloated format such as HAL doesn't have as much interest, since as @mamund describes it in his book, it only allows changes in addresses and not in objects nor in actions...

- Still talking about this "traditionnal client developper" : he will ignore the hypermedia format recommandations and hardcode his URLs like with any other API. Then, thinking I used a hypermedia-aware media type, I change my URLs. So I have broken a client that would not have been broken if I haden't used hypermedia... or am I missing something ?

- Adding entirely new actions or object properties (or even objects) will very rarely be supported by the clients. If they are human-driven, they won't display anything they don't know about beforehand (since they won't know what front-end style is appropriate). Otherwise (scripts, agents) they can't know the meaning of newly-added actions/properties and won't be able to exploit them... Unless the human developper changes the code. So for every new thing added to my API, my clients will have to adapt their code if they want to exploit it... which is what they would have done if I just put a v2 into production.
I see that I would be able to change some URLs and maybe methods, and won't have to maintain 2 versions, but are those 2 benefits really enough to justify the extra work needed to add hypermedia to my APIs ? How often do I really need to change a URL / method ?


Once again, I'm very interested in hypermedia, those are the only objections from my co-workers I can't answer yet. That's why I'm asking here ;)

Thanks !