A lot of the hypermedia philosophy is centered around the idea that API clients should work a lot like web browsers and plain-old Hypertext Markup Language. They should follow hyperlinks, leverage media types, cache data when they can, and intelligently take advantage of the meaning of hyperlinks whenever possible.
The problem with that is, web browsers are way more capable than HTTP clients developers are using to build API clients with.
Here are some things web browsers have become pretty good at:
- GET and POST requests
- Following links and redirects
- Discovering data structures via HTML forms and submitting data using that schema
- Using headers to negotiate content types
- Caching data when possible and expiring those caches
- Handling streaming data and chunked responses
- A bunch of stuff I'm probably forgetting
Here are some things the HTTP client in your typical standard library are good at:
- GET, POST, PUT, and DELETE requests
- Following redirects (if you manage to set the right options)
What's at play here is a chicken and egg problem. Client developers can't build on hypermedia principles until they are working at the level of hypermedia abstractions. Arming them only with HTTP requests and the ability to choose their encoding and schema poison is too low level.
Protocols like HAL or Collection+JSON could light a path to solving this problem. Rather than dealing in pure data, services and consumers work with data annotated with hypermedia-like semantics for traversing data structures and creating new data. If these protocols can gain traction, it's "simply" a matter of getting HTTP clients into widespread use (read: standard libraries in stable releases of your-favorite-programming-language) that are as good at HTTP as web browsers are. At that point, API providers and API consumers could start using hypermedia principles to build APIs for those who aren't interested in the mechanics of hypermedia.
Until then, it seems to me that putting hypermedia principles front-and-center is suboptimal. It's akin to telling someone who wants to use your website that they need to understand MVC patterns first. It's only going to discourage and confuse them.
