What are the characteristics of a "good" Web Service API?
We here at Notre Dame finished writing the MyLibrary Perl API a long
time ago. It does what is was designed to do, and we believe others
could be benefit from our experience. At the same time, the API is
based on Perl and we realize not everybody likes (or knows) Perl.
Some would say, "Why didn't you write in X?" where X is their
favorite programming language. Well, that is just not practical.
I believe the solution to the dilemma is a Web Service API against
MyLibrary similar to the Web Services API provided by Fedora. Any
scripts sends name/value pairs on a URL and gets back XML. This way
any language can be used against MyLibrary (which we now calling a
"digital library framework & toolbox").
Here are the only two working examples I have:
http://dewey.library.nd.edu/mylibrary/ws/?obj=facet&cmd=getAll
http://dewey.library.nd.edu/mylibrary/ws/?obj=facet&cmd=getOne&id=2
Try a few of errors:
http://dewey.library.nd.edu/mylibrary/ws/?obj=facet&cmd=getNone
http://dewey.library.nd.edu/mylibrary/ws/?obj=facet&cmd=getOne&id=45
http://dewey.library.nd.edu/mylibrary/ws/?obj=facet&cmd=getOne&id=x
I can create all sorts of "commands" like:
* get all facets
* get all terms
* get all librarians
* get all resources
* get all resources classified with this term
* create facet, term, librarian, or resource
* edit facet, term, etc.
* delete facet, term, etc.
Given such an interface library (MyLibrary) content can be used in
all sort of venues much more easily.
While I don't expect anybody here to know "what" commands to support,
I am more interested in the "how". What are the characteristics of
good name/value pairs? Should they be terse or verbose? To what
extent should the name/value pairs require a version number or a
stylesheet parameter? Besides being encoded in XML, what should the
output look like? What are characteristics of "good" XML in this
regard? Heck, then there is authorization? How do I disable people
from deleting resources and such.
This might be just an academic exercise, but with the advent of more
and more Web Services computing I thought I might give a MyLibrary
Web Services API a whirl.
--
Eric Lease Morgan
University Libraries of Notre Dame
code4lib_fridays++
|