News

I just finished reading the article "Using the OCLC WorldCat APIs" in Python Magazine by Mark Matienzo (fondly known as "anarchivist" in his online persona), and I have to say he did an excellent job of describing not only how to use our APIs effectively, but al

The Third OCLC Research Software Contest is well underway, but there is still time to enter. See the contest details for complete information. The winning entry will receive $2,500 and an expenses-paid trip to OCLC headquarters in Dublin, OH. Entries are due by the end of June and the winner will be announced before the end of July. Judging criteria includes: * Value to libraries, archives or museums * Use of OCLC services or data * Originality * Clean architecture and design The judges are: Kevin Clarke, Appalachian State University Karen Coombs, University of Houston Thom Hickey, OCLC Tod Matola, OCLC Jonathan Rochkind, Johns Hopkins University Ross Singer, Talis (and the winner of the Second OLC Research Software Contest) Roy Tennant, OCLC Don't let this opportunity pass to pick up a cool $2,500 and the chance to have your coding prowess recognized! Roy Tennant OCLC Research

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:

1. it confuses the wrapper for the package;
2. 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.
3. It focuses attention on implementation detail, rather than the user- or business value of the actual service.
4. 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.
5. 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."

[full version of article A Web Services Taxonomy (PDF 84k)] A Web Service, according to a standard definition, is "a software system designed to support interoperable machine-to-machine interaction over a network." 1 To put it another way, a Web Service is some useful service offered (usually) on the Internet, designed as a sort of building block you can use any way you want. So, for example, Google Maps, a free service that dynamically draws maps of any location and locates addresses, has been used by thousands of people to build new services such as crime-report maps and real-estate listing tools, Another way to wrap your mind around Web Services is to consider a range of well-known ones and what they do. That's what the chart below does, with services such as Paypal, Google, Twitter, and Sabre, the airline-reservations system. (click on chart to see full-size): This chart represents a taxonomy, or classification, of Web Services, constructed by characterizing all services according to two factors:

1. Data quality: from simple/commodity to complex/unique
2. Transaction level: from basic lookup to real-world transaction.

The full version of this article, A Web Services Taxonomy (PDF 84k), defines what is meant by those terms, and discuss representative examples of Services that exhibit varying degrees of these characteristics. Based on this, I suggest that the Services with the most usage, customer value, and/or revenues typically have more complex/unique data, and/or are more transactional. See also the above chart in full size, or the full article (PDF 84k).