[rhizome31]

I've read most of the book RESTful Web APIs, which advocates Hypermedia as a way to stop having to create client-specific libraries for each and every Web API. But the book doesn't say much about creating such clients.

Is there such a generic Hypermedia client for Python?

How does this affects performance? Navigating through the maze of a Hypermedia API requires many more requests than just hitting a known endpoint, doesn't it? Do hypermedia clients provide client-side caching?

My other concern is that those APIs might be harder to learn than ad hoc fiat standard. The reason why RESTful-ish APIs have been successful is because they don't add any overhead on top of the things they're representing. At first glance, stuff like JSON-LD, Siren, HAL, etc. seem to be bringing back the complexity of things like SOAP that people have fled from.

[gamache]

The client space is slowly filling in. There are a bunch of clients which still leave the plumbing exposed (a couple good ones are HyperClient.rb[1] and HyperAgent.js[2]) -- it still feels like you're making HTTP requests.

One of the things I like most about hypermedia is that the hyperlinks can represent a complete set of functions which can be applied to an object. In other words, each object contains its own method list. This fits well in languages which get to implement catch-all methods, like Ruby, and I couldn't resist coding up a client that worked that way.

(There's room for this sort of trickery in near-future ECMAScript too, with Proxy[3]. I would really like someone to do this and I would kind of like it to not be me.)

When you lay out your API according to that philosophy, and cache a few "stepping-stone" objects you'll be traversing often, hypermedia APIs don't seem so inefficient at all.

As to your last point: take a look at HAL[4]. It sits alongside a "traditional" API layout very nicely, essentially adding "_links" and "_embedded" which can be safely ignored by non-hypermedia clients. The HAL spec is extremely sane.

[1] https://github.com/codegram/hyperclient

[2] http://weluse.github.io/hyperagent/

[3] https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

[4] http://stateless.co/hal_specification.html

[rhizome31]

Thank you and Steve for your replies.

You both seem to recommend HAL over other Hypermedia formats. In their book, Richardson & Amundsen mention that HAL doesn't allow to tell the client which HTTP methods to use when doing state transitions. They say that HAL is therefore only suited for read-only APIs. What do you think of that?

[darrelmiller]

Link relations can be designed that indicate which HTTP methods are allowed. HAL is heavily dependent on conveying semantics via link relations, which is something that some people don't like doing.

Consider the oauth2-token link relation defined here[1]. The definition of this link relation refers to RFC 6749 [2] which states that it is necessary to pass a application/x-www-form-urlencoded body using POST.

[1] https://tools.ietf.org/html/draft-wmills-oauth-lrdd-07#secti... [2] https://tools.ietf.org/html/rfc6749#section-4.1.3

[gamache]

Formally, they're absolutely right. Information like that is out of band with HAL.

In practice, I deal with it by sticking to HTTP verb conventions and specifying what to do in the documentation.

It's not automatic -- it'd be e.g. rsrc.somelink.post(params) instead of rsrc.somelink(params) in HyperResource's case -- but it works, and any human who knows what the 'somelink' rel is supposed to do might also be expected to know how to use it.

[steveklabnik]

Yup, this is largely the year of the client.

> Python?

There are some libraries, expect more to spring up soon.

> How does this affect performance?

This kind of question is incredibly broad. In ways it's more efficient, in ways it's less. It Depends.

That said, as you alluded to, caching should be very prevalent, so that helps.

Also, it's not like you have to make 5 requests any time you want to do anything: the point is that you follow the application's state along. Just one request per transition. A maze is a pretty decent analogy, actually...

> harder to learn than an ad hoc fiat standard

They may _seem_ harder to learn, but you have to re-learn every single ad-hoc standard over and over and over and over. If you learn HAL, you can speak to any number of APIs that use HAL. Plus, you say 'complexity,' I say, 'no surprises.' Everything is actually enumerated for you, so it should be easier to learn. No hidden assumptions.

Furthermore, as you're more familiar with the format, the details fade into the background. I'm sure you don't read RFC 4627 every time you want to deal with a JSON-based API, either.