i only have an opinion on the nature of the xml to return, and only in the case of lists of stuff: Atom or RSS. i'm really cursing myself for having fallen into the trap of "hey, with xml i can create my own formats" too often. best regards, robert On 6/29/07, Eric Lease Morgan <[log in to unmask]> wrote: > 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++ >