Marieke Guy of JISC (UK) has released the long-anticipated "Good APIs" study, in two parts:
- Report 1: JISC Good APIs Management Report: "a background to API use in the UK HE [Higher Education] sector, the potential benefits of the provision of APIs and the challenges this provision can instigate. The report also reviews potential problems developers can face when using third-party APIs."
- Report 2: API Good Practice: "provides a number of good practice techniques for provision of and consuming APIs. The content of this report is based primarily on feedback provided from the developer community."
What came through strongly for me in this report was
ease of use:
"make sure that there is a low barrier to access. The maximum entry requirements should be a login (username and password) which then emails out a link.
"If you need to use a Web API key make it straightforward to use. You should avoid the bottle neck of user authorisation, an overly complex or non-standard authentication process. One option is publish a key that anyone can use to make test API calls so that people can get started straight away. Another is to provide a copy of the service for developers to use that is separate from your production service. You could provide a developer account, developers will need to test your API so try to be amenable."
On the down side, I think the framing/title, "Good APIs", leads to a conceptual confusion between the notions of "API" vs. "Web Service". In some places, the JISC discussion is about the Service -- for example, finding out what users need first. In other places, the report recommendations are clearly about APIs specifically, for example when they talk about method naming conventions.
I would argue that, to speak clearly about this domain, one needs to distinguish between these two concepts, and use the terms deliberately.
So, a Web Service is a Web-based application oriented towards machine transactions. On the other hand, an API, or Application Programming Interface (not "Program" Interface), is
a well-defined method for accessing a Service. (the machine-usability characteristic of APIs is mainly a consequence of this well-definedness).
As an analogy,
Web Services are like local or long-distance phone service, whereas the API is like a phone jack. A Service can have many APIs, like the various ways one might connect to long-distance phone service. Also, the mere existence of an API does not necessarily mean that the service behind it does something worthwhile, or does it with sufficient quality or reliability to meet your needs.
A real, production-quality Service includes not only API(s) but documentation, a service-level agreement, performance benchmarks, and support.
Finally, it's worth noting that a Web Service, in the general sense, might be delivered to users via means we wouldn't call APIs: for example, by depositing an updated Linked Data set to a public data repository.
The problems with using "API" to mean Web Service include the following, in my opinion:
- it confuses the wrapper for the package;
- it tends to a view of Web Services as just simple data services, request-in and data-out -- which is only one type of WS, and often the least valuable.
- It focuses attention on implementation detail, rather than the user- or business value of the actual service.
- It hides the fact that a useful service might well, over time, have a number of different APIs implemented for it, as different usages, protocols, and environments emerge.
- it tends to make people think of Web Services as just a matter of "exposing" some data or functions from an existing application.
Also, speaking of APIs separates us from the dominant technical and standards discussions, and rigorous term definitions, which center around the W3C and its Web Services program
I know, it might seem to be quibbling, to focus on terms. However, I've seen over and over that major issues are often decided in the choice of framing and vocabulary, rather than in the "actual" discussion that follows.
In any case, check out Marike's well-done and nicely consultative report, and learn more about how to make Web Services be, in Coleridge's famous phrase, "companionable forms."
Follow the OCLC Developer Network: