Mashup Guide

Readers of my book know that I'm an avid user of social bookmarking and online bibliographic systems. As  a big fan of Zotero ("a free, easy-to-use Firefox extension to help you collect, manage, and cite your research sources"),  I have been looking for  ways to further integrate Zotero (both the client and the web front end) into my workflows.  Specifically, I would like to experiment with integrating Zotero into my teaching this semester,  specifically to help my students and I  share references.

I've played with scripting Zotero from within the web browser using Chickenfoot.  However, a fully fleshed out Zotero REST API will, I think, be even helpful in tying Zotero to other applications.  There is a Zotero REST API under development, though it is currently limited and not well publicized.

The best publicly available documentation of the API as it stands that I know of is Jeremy Boggs' code phpZotero.   Reading it taught me how to make some basic calls.

(Note: I currently have two separate Zotero accounts:  a personal one (rdhyee) and one for my course (mixingandremixinginfo).  Ideally, I'd rather manage only one account but have two because, from what I understand, there is no fine-grained privacy control that would let me  keep some references private while leaving most public.    Moreover, it seems that the REST API can read only public items for now — so I'll be applying it to mixingandremixinginfo for now. )

Let me write out what you can do with the API to get started.

1. Create a key at  Zotero | Settings > Feeds/API (Though I've used a key, I don't see any indication of key usage in my panel — is this a bug?)
2. Go to the Zotero privacy tab to check "Publish Entire Library" and "Publish Notes" to make the items (and optionally notes) visible to your API key.
3. Figure out the userID for the account.  You can do so but doing a HTTP GET on
   http://www.zotero.org/api/users/{username} e.g.,
   http://www.zotero.org/api/users/mixingandremixinginfo — see

   <?xml version="1.0" encoding="utf-8"?>
   <entry xmlns="http://www.w3.org/2005/Atom" xmlns:zapi="http://zotero.org/ns/api">
       <title>mixingandremixinginfo</title>
       <author>
           <name>Zotero</name>
           <uri>http://zotero.org</uri>
       </author>
       <id>http://zotero.org/users/119961</id>
       <published>2010-01-26T22:43:38-05:00</published>
       <updated>2010-01-26T22:46:11-05:00</updated>
       <link rel="self" type="application/atom+xml"
           href="http://api.zotero.org/users/119961"/>
       <link rel="alternate" type="text/html"
           href="http://zotero.org/mixingandremixinginfo/119961"/>
       <content type="application/xml">
           <zapi:userslug>mixingandremixinginfo</zapi:userslug>
           <zapi:profile>
               <zapi:affiliation><![CDATA[UC Berkeley]]></zapi:affiliation>
               <zapi:bio><![CDATA[<p>This is a public account associated with the Mixing and Remixing Information course at the UC Berkeley School of Information</p>]]></zapi:bio>
               <zapi:disciplines><![CDATA[Information Science and Technology]]></zapi:disciplines>
               <zapi:location><![CDATA[Berkeley, CA]]></zapi:location>
               <zapi:realname><![CDATA[Mixing and Remixing Information]]></zapi:realname>
               <zapi:website><![CDATA[http://blog.mixingandremixing.info]]></zapi:website>
           </zapi:profile>
       </content>
   </entry>
   

   and then parse out for the id element   (e.g., 119961)

4. Now to get items and collections, note that the base URL for the API ishttps://api.zotero.org/
   and that you can use two
   parameters:  username,  apiKey in
   curl -v -k -X GET "https://api.zotero.org/users/119961/items?username={username}&apiKey={apiKey}"
   to return publicly visible items.
5. You can get data about a  specific item (e.g.,http://www.zotero.org/mixingandremixinginfo/items/102472156)with

   curl -v -k -X GET "https://api.zotero.org/users/{userid}/items/{itemid}?username={username}&apiKey={apiKey}"

   e.g., curl -v -k -X GET "https://api.zotero.org/users/119961/item/102472156?username=mixingandremixinginfo&apiKey={apiKey}"

6. Jeremy's phpCode hints at other things you can read from the API, including user collections and their  items, that I've not tried accessing.  However doing so should be straightforward.

Don't consider what I've written here as definitive by any means since  I don't know of any publicly available official documentation.   I'm eager to see the further development of the API, including the ability to access more data (about users,  groups,  etc) and the ability to write to Zotero servers.

Comments welcome!