There is something in the main report that talks about types of APIs:

“Although some have found it useful to make a distinction between traditional and Web type of API for this report some better distinctions might include:

• projects which provide an API versus projects which are actually developing a Standard API (e.g. OpenDOAR offers an API, SWORD is a project defining one).

• APIs which are about offering simple access to resources (e.g. RESTful) versus ones which are about exploiting some re-usable function (e.g. APIs for workflow systems)

• APIs which are tied to programming languages versus those which are not (SOAP/ HTTP REST/XML RPC)

We’ll have a go at expanding on this to differentiate further.

Thanks

Marieke

One of the key tenets of the REST architectural style, the set of principles which was used to guide the development of foundational Web standards like the URI syntax and the HTTP protocol, is that of the “uniform interface”; i.e. that components within the system expose the same interface, rather than components within different subsystems exposing different interfaces. I don’t see how this fits with a notion that APIs are “unpredictable”.

I think this particular point is a symptom of a the more general point that the report probably needs some discussion of the different contexts within which “APIs” are designed and deployed, and the different “affordances” of those different contexts. What is “good” in one context isn’t necessarily “good” in another.

The globally distributed, highly devolved context of the Web is a very different different context from that of, say, the systems of one particular organisation. And so application interfaces within those two different contexts may have very different requirements and characteristics. The foundational standards of the Web were designed to support the requirements of that particular context, and they exhibit certain properties and characteristics specifically to meet the particular requirements of that context.

Without this sort of differentiation, it seems to me it is very difficult to make particular recommendations about what constitutes a “good” API.

The treatment of REST here seems far too minimal but given your current structure I’m not sure where it would go.

Ditto any thinking about access control / identity in 1.8. The reference to Linked Data in 1.8 seems out of place (though treatment Linked Data and REST should probably be co-located).