Mirlynapi:Home
From MLibrary API
Contents |
[edit] Quick overview
The Mirlyn API is a simple, REST-ful interface into the University of Michigan's University Library OPAC, Mirlyn.
We currently provide three sets of data to output (basic, circulation status, and full MARC) in two formats (XML and JSON). If you use the API, or would like to use the API if it had additional functionality, drop Bill Dueber a note.
[edit] Everything is a list
The basic design of the API is to use well-constructed URLs to represent lists of records. While many lists have (or should have) only one item, it's important to remember that you're always points at lists, which means you usually want to request a specific set of records within that list.
[edit] REST-ful URLs for queries
The URL to represent a query generally looks like (split across lines for legibility):
http://mirlyn.lib.umich.edu/cgi-bin/api
/<dataToSendBack>.<formatOfData>
/<indexToSearch>
/<searchString>
?records=<recordspec>
There is also a "freeform" option where instead of indicating a single index to search, you can specify a whole query in valid CCL (Mirlyn's search syntax):
http://mirlyn.lib.umich.edu/cgi-bin/api /<dataToSendBack>.<formatOfData> /freeform ?query=<validCCL> &records=<recordspec>
[edit] Explanation of the parts of the URL
[edit] dataToSendBack: Specifying what data are returned
All successful searches return searchInfo indicating what the search was, how to re-construct the search for the normal Mirlyn web interface, etc.
In addition to the searchInfo, there are three datasets that can be requested:
- marc returns the full MARC record, including inserted tags indicating some basic information about which libraries have the item, its type (book, CD, etc), links to the Michigan Digitization Project if possible, and aggregated availability. It uses either MARC-XML (without the namespace declaration) or MARC-JSON, a format I made up just for this purpose. See the Example MARC-XML title and/or the MARC-JSON title.
- basic returns just the basics, with English (as opposed to MARC) tags. See the example Basic XML or JSON titles.
- circstatus doesn't return any real bib-level data at all, except the unique identifier in the id field. What it does provide is item-level data (e.g., at the level of the actual physical item, assuming there is one). Its main content is a set items, each of which has barcode, library, call number, and availability information specific to that item. XML and JSON examples may help clarify.
[edit] formatOfData: Specifying the output format
- XML is returned without namespaces due to the current difficulty working with namespaces in many scripting languages (Ruby, I'm looking at you). There may, in the future, be an option to include the MARC XML namespace in MARC XML records if folks want it.
- JSON is the JavasScript Object Notation, a format based on the string-literal notation used to describe strings, arrays, and hashes in javascript. There are libraries for any languages you're likely to use, and dealing with JSON in Perl, PHP, Ruby, Python, etc. is often much easier that working with XML if you're unfamiliar with the latter. As noted MARC data is returned as MARC-JSON.
[edit] Specifying what search to perform
indexToSearch (see full list of possible values)
Many (all?) of the indexes available to search Mirlyn from the web API are available, and most have been given aliases so a good guess will work a lot of the time. Strings like title, author, keyword, isbn, etc. all work as expected.
The full list of possible values is on its own page for easy reference.
searchString
Generally, the search string will just be a single identifier, name, etc. The following rules flesh this out:
- You can include multiple words, but you must URI-encode the whole thing. Generally, that means replacing spaces with '%20', e.g. /author/Curt%20Bonk.
- ISBNs and ISSNs will automatically have dashes stripped, so don't worry about that.
- Semi-colons express a logical 'OR' . To grab several ISBNs, you could search as /isbn/0596000278;097669400x?records=all. Note that even though you're specifying multiple search strings, you still have to request all the records explicitly.
recordspec
The recordspec dictates what records get returned, based on their sequence in the search set (the first record -- the one that would be on the top of the page if you did the search in the Web OPAC, is record 1).
The recordspec can have the following formats:
- records=1 (get the first record)
- records=1,3 (get the first and third records)
- records=1-10 (get the first ten records)
- records=11-20 (get the next ten)
- records=1,3,5-9 (get the first, third, and fifth through ninth records)
- records=3,1-2 (get the first three records, but in weird order)
- records=all (get all available records, unless the caveats below apply)
The following caveats apply to the recordspec:
- You can't ask for more than 30 records at a time. If you do, only the first 30 records that match your recordspec will be returned.
- If no recordspec is given, the default is to return only the first record
- If you ask for more records than are available (e.g., records=1-10000), you'll just get what's available without throwing an error.
- records=all is functionally equivalent to records=1-1000000.
[edit] Simple Examples
- Find a single record based on the UM system number, returning MARX XML
http://mirlyn.lib.umich.edu/cgi-bin/api/marc.xml/uid/005549268?records=1
- A list of the first 10 item with author "Bonk" in basic.json format
http://mirlyn.lib.umich.edu/cgi-bin/api/basic.json/author/bonk?records=1-10
- Circstatus for a book
http://mirlyn.lib.umich.edu/cgi-bin/api/circstatus.xml/uid/005549268
- Basic data about two specific books, in json
http://mirlyn.lib.umich.edu/cgi-bin/api/basic.json/isbn/0596000278;097669400x?records=all
