- Who wrote this?
- How do you pronounce “unAPI”?
- What does “unAPI” mean?
- How is it being developed?
- Why does the world need another protocol?
- Didn’t you see that Ray Ozzie and Microsoft invented the web clipboard already?
- Why not Atom?
- Why not OpenSearch?
- Why not OAI-PMH?
- Why not OpenURL?
- Why not SRU?
- Why a “microformat”?
- Why the link autodiscovery tag?
- Why use GET param/values when you could just use fixed paths?
- Why use an XML-based formats list?
A group of people assembled on the gcs-pcs-list wrote unAPI.
Dan Chudnov is writing this FAQ.
However you want. “un A.P.I.” (like `un’ en francais), “un-API” (like “not an API”), “una P.I.” (like `una’ en espanol), “un-appy”, “you-nappy”, it all works.
It’s intended to evoke both “one API” and “not an API”.
An “API” is an “application programming interface”, or an interface for software developers for programming an application.
How is it being developed?
We are using the ROGUE 05 process; the list of record for all discussion is the gcs-pcs-list. Yes, the rules are arbitrary, but its goals are to produce something simple, quickly, and it has arguably succeeded in helping to meet these goals. The process is open and all are invited to participate; those implementing the specification and sharing their implementation experience and code will have ultimate say over the final version.
Why does the world need another protocol?
For several reasons, first being that we don’t need another protocol. We’re excited that everybody is writing their own APIs to their own apps but we really want everybody to do what unAPI does the unAPI way. So it’s supposed to be a little common technique we can all use independent of how all the other APIs work.
Didn’t you see that Ray Ozzie and Microsoft invented the web clipboard already?
Yes, we read that somewhere, and the stuff they demonstrated looks very cool. But we first read about the “web clipboard” idea in Bill Burcham’s Baby Steps to Synergistic Web Apps post on lesscode.org six months ago. Before that, some of us wrote about something similar a year ago (scroll down to the later section called “Adding a Layer…”). These things have been in the air for a while… everybody’s just getting a handle on what to call it and how to do it now.
Why not Atom?
The Atom Publishing Protocol is very cool and we like it a lot. But in Atom there’s a one-to-one relationship between objects available (resolvable) from a specific URI and the actions Atom enables for that object at that URI. In an Atom application you can interact through Atom with those URIs in your application, and that’s it.
unAPI covers the use case when your application supports interaction with objects at a URI distinct from those that are resolvable directly through your own application. If, say, you have a blog at example.com/myblog, and you write about a book with URI urn:isbn:123456789X in a blog entry, you can use Atom to interact with your blog entry at example.com/myblog/entry/456 or whatever it might be, but using unAPI you could interact with the book through example.com/myblog/unapi?uri=urn:isbn:123456789X.
To the best of our understanding, the Atom Publishing Protocol is not designed to handle this use case, which is not explicitly within the scope of Atom.
OpenSearch is very cool and we like it a lot. But it is a search protocol, not a known item retrieval protocol. If you know that a webapp has information about urn:isbn:123456789X, and search that value through an OpenSearch interface for that webapp, you just don’t know what you’ll get… maybe there will be sixteen “search hits” that reference that object somehow. Or maybe the site won’t actually index identifiers like that so even though you know the site carries information about that book, you might not be able to find it through a search interface.
unAPI addresses this problem by providing an HTML microformat for indicating exactly when information about an item is available through the unAPI interface, and a simple pair of functions for interacting with that known item through the unAPI interface. You know exactly what you’ll get.
To the best of our understanding, the OpenSearch specification is more broadly useful but OpenSearch instances cannot be reliably assumed to be useful for this specific objective, which is not an objective of OpenSearch.
OAI-PMH is great and we like it a lot. You can easily do what unAPI does over OAI-PMH. Indeed that’s actually where we started… before there was unAPI, we tried something called “COinS-PMH” and found it was basically able to do what unAPI does.
The problems are that (a) few outside of the library community know what OAI-PMH is, (b) fewer outside of the library community know what COinS is, (c) still fewer outside of the library community know what the OpenURL specification (on which COinS is based) is, and (d) “COinS-PMH” is a terrible name for something like this.
unAPI has a simple name and is intended to be so simply specified that everybody in the world can understand it quickly.
OpenURL is great and we like it a lot. You can easily do what unAPI does over OpenURL. The main problem with OpenURL is that it’s an overly complex specification for just the simple objectives unAPI addresses.
unAPI sets out to achieve just these simple objectives, and nothing more. Because of this we hope many people will find it approachable and useful.
SRU is cool and we like it a lot. Like with OpenSearch, though, it’s a search protocol, and the same issues hold with SRU as they do for OpenSearch.
About the spec itself
The microformats.org project has done amazing work with the idea they pioneered and we think the world hasn’t even begun to feel the potential benefits their combination of techniques offers. We are simply emulating their approach for the purpose of explicit indication of unAPI-available objects.
If the microformats.org project folks saw a benefit in a microformat for URIs, we would defer to their specification instead of writing our own.
Why the link autodiscovery tag?
It has proven effective in other applications, especially in feed autodiscovery, among others.
Why use GET param/values when you could just use fixed paths?
We debated this quite a bit but determined that GET param/values were simpler and more likely to be usable by more people, especially those with hosted applications in server environments where they have no ability to rewrite URL paths.
Why use an XML-based formats list?
It is simple enough that modern languages and web frameworks should be able to generate it easily, and most programmers should be able to process it easily.
