Hacker News Reader

Comment by icebraining | Hacker News Reader

But if you're writing an API to access a proper web application, it needs more than just data retrieval, and it needs ACL, and it needs to not show things to certain people, and allow bi-directional communication, and all sorts of other things.

And HTML webpages don't have that? Let's take HN:

* ACLs: ✔ I have an account and I can't post as other people.

* Hide things from certain people: ✔ I can't see your email

* Allow bi-directional communication: ✔ I can post this very message.

View on HN

My big reason to have a separate API falls under "all sorts of other things": The machine API exposes data objects. The human API (HTML web pages) defines interfaces to manipulate the data objects. In the presentation layer (human API) I manage collections of data objects, conditional inclusion of other data objects, etc. The human API is not a simple resource-access system, but contains logic governing interaction and relations between data objects. The machine API layer is basically a controlled data access layer.

The human API also exposes data objects. It also sends extensions (CSS, Javascript) to the client that allow it to present the data and make additional API calls. This idea of extending the client program is part of REST.

The machine API also handles interaction and relations. The representation of a collection object will contain URLs of the elements. There should be hints on how to compose a request that updates the object.

So I just spent half an hour trying to illustrate a simple counter-example, but for each of the half-dozen apps I have considered I see how it could be organized into a unified structure differentiating machine/human API by the requested content type. I'm not sure if I would prefer that in practice, but I think I am going to have to try it. The idea of having a single structure for the API is too elegant not to try.

Works for this case. Doesn't work for things I've worked on. :)

Why not?

Reply on news.ycombinator.com