Services

If you're a member of the OCLC Developer Network (aka, a member of the WC-DEVNET-L listserv community), then you already heard about this update awhile back. But I realized we hadn't posted it officially to the blog yet--so here we are. The JSON format option for library holdings data is helpful for WorldCat Search API-using developers who want to supply a list of nearby WorldCat libraries that hold the materials in question.

Another question that was asked at the OCLC Web Services Bootcamp at VALA was "Can I find the earliest edition with xID?" The answer is Yes The getEditions response from xISBN has fields for both edition and year published information. Edition information is sometimes missing so the best way to handle finding the earliest edition is to use the year field. There are a couple different ways one might do this. One could use an XSL to sort the nodes ascending by year and then pull out the ISBN or OCLC Number of the first one.

One question that was asked at the OCLC Web Services Bootcamp at VALA was if the xISBN service handled both 10 and 13 digit ISBNs. The answer is yes. You can send either a 10 or 13 digit ISBN for the same book to the service and you will get back the same response. Case in point Learning Python has both a 10 and 13 digit ISBN.

In conjunction with the OCLC API Mashathon at VALA next week, I'm posting a tutorial on how to use the xISSN service to enhance local information about serials. This tutorial discusses how to use the xISSN services to enhance an existing library user interface--such as a catalog--by adding information from the xISSN service. It demonstrates how to add two things on the fly to a library catalog full record display screen:

Now anyone and everyone can create apps and mash-ups using library data from WorldCat, the world's largest library catalog. Because the WorldCat Basic API is here! This new API is a simplified version of the WorldCat Search API. Send it RESTful URI queries in OpenSearch, and it retrieves results in RSS or Atom.

Well right now it is -- number 7 in Google Search results for 'search APIs' sharing company with some pretty famous search APIs. I wouldn't classify this as 'huge news' but fun to note. Report in with your new WorldCat API consuming applications -- keep us up to date! Don

New limit by holdings for WorldCat Search API Good news for WorldCat Search API WSkey holders. The WorldCat Search API has been enhanced.

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

We added a few new features to xID service: - xISSN now supports ISSN-L and RSSURL field, such as http://xissn.worldcat.org/webservices/xid/issn/1095-9203?method=getMetadata&fl=issnl,rssurl ISSN-L data is obtained from ISSN agency, and rssurl is obtained from ticTOCS. xISSN also adds values to both data set, for example, xISSN automatically adds RSSURL to all ISSNs in same group. - xOCLCNUM now supports OCLC workid, such as: http://xisbn.worldcat.org/webservices/xid/oclcnum/55847258?fl=owi And you can query by workid as well: http://xisbn.worldcat.org/webservices/xid/owi/owi718389 I highly recommend using "owi[0-9]" in its whole format when you came upon workid, this will be very helpful for identifying workid from any web pages and facilitates interoperability and mashup. For more information, please check xISSN and xOCLCNUM API.

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."