formatted references via API

206 views
Skip to first unread message

Dan Stillman

unread,
Dec 8, 2010, 4:54:42 PM12/8/10
to zotero-dev
We're pleased to announce that it's now possible to generate formatted
references via the Zotero API.

Updated documentation is available at
http://www.zotero.org/support/dev/server_api

We've implemented a node.js-based wrapper around Frank Bennett's
excellent citeproc-js CSL processor (which is also used in Zotero 2.1)
and are using it as a backend service. We'll be checking in the code for
that service to https://www.zotero.org/svn/citeproc-node/trunk/ soon.
The data server generates citeproc-js JSON for requested items and
passes it to citeproc-node.

There are currently two possible bibliographic modes, format=bib and
content=bib:

format=bib will return a formatted bibliography as XHTML with inline
CSS. For performance reasons—with the API, not with citeproc-js—this is
currently limited to 150 items. Any more will return an error. The
returned XHTML is not currently marked up with RDFa or COinS (here or in
the client), but that's one thing we'll be looking to add.

- content=bib (which is really format=atom&content=bib, but format=atom
is the default) will return a formatted reference for each item in the
item's Atom <content> block. Since the data server generates these
references individually, using numeric styles doesn't make sense for
this mode (since they'd all be "1").

Styles are currently passed as short names of Zotero Style Repo styles.
Support for arbitrary style URIs is forthcoming.

We're still tweaking and optimizing this—among other things, additional
caching and support for If-Modified-Since are needed—so feedback is
appreciated.

Examples:

https://api.zotero.org/groups/1/collections/42ZCTF3U/items?format=bib&style=chicago-note-bibliography

https://api.zotero.org/groups/1/collections/42ZCTF3U/items?content=bib&style=apa

- Dan

Bruce D'Arcus

unread,
Dec 8, 2010, 5:48:55 PM12/8/10
to zoter...@googlegroups.com
On Wed, Dec 8, 2010 at 4:54 PM, Dan Stillman <dsti...@zotero.org> wrote:
> We're pleased to announce that it's now possible to generate formatted
> references via the Zotero API.
>
> Updated documentation is available at
> http://www.zotero.org/support/dev/server_api
>
> We've implemented a node.js-based wrapper around Frank Bennett's excellent
> citeproc-js CSL processor (which is also used in Zotero 2.1) and are using
> it as a backend service. We'll be checking in the code for that service to
> https://www.zotero.org/svn/citeproc-node/trunk/ soon. The data server
> generates citeproc-js JSON for requested items and passes it to
> citeproc-node.

Awesome!

But a quick question: can one not feed it JSON items directly?

Bruce

> There are currently two possible bibliographic modes, format=bib and
> content=bib:
>
> format=bib will return a formatted bibliography as XHTML with inline CSS.
> For performance reasons—with the API, not with citeproc-js—this is currently
> limited to 150 items. Any more will return an error. The returned XHTML is
> not currently marked up with RDFa or COinS (here or in the client), but
> that's one thing we'll be looking to add.
>
> - content=bib (which is really format=atom&content=bib, but format=atom is
> the default) will return a formatted reference for each item in the item's
> Atom <content> block. Since the data server generates these references
> individually, using numeric styles doesn't make sense for this mode (since
> they'd all be "1").
>
> Styles are currently passed as short names of Zotero Style Repo styles.
> Support for arbitrary style URIs is forthcoming.
>
> We're still tweaking and optimizing this—among other things, additional
> caching and support for If-Modified-Since are needed—so feedback is
> appreciated.
>
> Examples:
>
> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?format=bib&style=chicago-note-bibliography
>
> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?content=bib&style=apa
>
> - Dan
>

> --
> You received this message because you are subscribed to the Google Groups
> "zotero-dev" group.
> To post to this group, send email to zoter...@googlegroups.com.
> To unsubscribe from this group, send email to
> zotero-dev+...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/zotero-dev?hl=en.
>
>

Dan Stillman

unread,
Dec 8, 2010, 5:57:10 PM12/8/10
to zoter...@googlegroups.com
On 12/8/10 5:48 PM, Bruce D'Arcus wrote:
> On Wed, Dec 8, 2010 at 4:54 PM, Dan Stillman<dsti...@zotero.org> wrote:
>> We're pleased to announce that it's now possible to generate formatted
>> references via the Zotero API.
>>
>> Updated documentation is available at
>> http://www.zotero.org/support/dev/server_api
>>
>> We've implemented a node.js-based wrapper around Frank Bennett's excellent
>> citeproc-js CSL processor (which is also used in Zotero 2.1) and are using
>> it as a backend service. We'll be checking in the code for that service to
>> https://www.zotero.org/svn/citeproc-node/trunk/ soon. The data server
>> generates citeproc-js JSON for requested items and passes it to
>> citeproc-node.
> Awesome!
>
> But a quick question: can one not feed it JSON items directly?

At the moment we're not opening up the backend citation service to
direct access, but we may do so once we've seen how it handles API
requests. (And, of course, with the wrapper code we release, anyone will
be able to run an equivalent service themselves.)

Erik Hetzner

unread,
Dec 9, 2010, 3:31:39 AM12/9/10
to zoter...@googlegroups.com
At Wed, 08 Dec 2010 16:54:42 -0500,

Dan Stillman wrote:
>
> We're pleased to announce that it's now possible to generate formatted
> references via the Zotero API.

This is great! I wish you would have announced it about 1 week ago,
though, before I finished up hacking a mozrepl connection to get
citations from zotero for reStructuredText and org-mode. ;) Now I need
to create an alternate implementation that uses this system.

Seriously, this is a better way to do it, so I am happy about that.

By the way, is this a unique key in Zotero-land:

egh/3A8VMRJ5

That is, does the combination of username and key provide a globally
unique identifier for a bibliographic item?

best, Erik

Bruce D'Arcus

unread,
Dec 9, 2010, 8:21:59 AM12/9/10
to zoter...@googlegroups.com
On Thu, Dec 9, 2010 at 3:31 AM, Erik Hetzner <e...@e6h.org> wrote:

....

> By the way, is this a unique key in Zotero-land:
>
>  egh/3A8VMRJ5
>
> That is, does the combination of username and key provide a globally
> unique identifier for a bibliographic item?

... and has there been any movement on resolving the problem of tying
formatting to unique, user-specific, items?

Bruce

KlausR

unread,
Dec 9, 2010, 10:54:56 AM12/9/10
to zotero-dev
Thanks for this development - really great.

Do you have suggestions how I could implement this on my website.
XMLHttpRequest runs into cross-domain restrictions.

It would sure be extremely comfortable to have a button with an embed
code next to each collection.
But in the mean time, what would be a quick and dirty solution for
those who have just little access to the resp. webserver?

Thanks
Klaus

Dan Stillman

unread,
Dec 9, 2010, 11:17:58 AM12/9/10
to zoter...@googlegroups.com
On 12/9/10 3:31 AM, Erik Hetzner wrote:
> By the way, is this a unique key in Zotero-land:
>
> egh/3A8VMRJ5
>
> That is, does the combination of username and key provide a globally
> unique identifier for a bibliographic item?

Yes, though there's currently no great way to resolve a username to a
userID, which the API requires. We're considering supporting usernames
directly in API requests.

Dan Stillman

unread,
Dec 9, 2010, 11:19:26 AM12/9/10
to zoter...@googlegroups.com

Sorry, what problem are you referring to?

Dan Stillman

unread,
Dec 9, 2010, 11:40:09 AM12/9/10
to zoter...@googlegroups.com

The API isn't really meant to be used client-side at the the moment.
That'd cause a much greater performance hit than (cached) server-side
requests, so it'd have to wait for further optimizations, and we'd also
have to add support for something like JSONP, which is designed to get
around cross-domain restrictions.

For sharing a collection from a non-public library, there are also
access considerations�you'd have to either embed a key with access to
your entire library or else make a group just for this. More
fine-grained permissions would probably be necessary for embeddable keys.

If there's significant demand for JS-based access we can explore this,
but it's unlikely to happen in the very near future.

Erik Hetzner

unread,
Dec 9, 2010, 11:53:58 AM12/9/10
to zoter...@googlegroups.com
At Thu, 09 Dec 2010 11:17:58 -0500,

Dan Stillman wrote:
> Yes, though there's currently no great way to resolve a username to a
> userID, which the API requires. We're considering supporting usernames
> directly in API requests.

Thank would be helpful.

As background, I have implemented a library (a “directive”) [1] for
reStructuredText [2] that allows a user of that system to insert a
citation to an item in the following way:

.. zotero:: 3A8VMRJ5

It would be nice to allow globally unique identifiers, as in:

.. zotero:: egh/3A8VMRJ5

instead, as this would allow users to cite other users items as well
as their own, and, more importantly, would allow one user to process
another user’s document. I suppose this feature is dependent on
resolving usernames.

What would probably be more popular would be to enhance luaTeX to
allow a similar feature, so that TeX users no longer rely on the (in
my mind) outdated BibTeX, but can instead write documents as:

... \cite{egh/3A8VMRJ5} ...

\bibliography

using Zotero to format their citations at the time the document is
generated, bypassing completely any export of a BibTeX document or
need to call BibTeX.

As a final thought, is there any chance that we could use the same
interface to generated citations using a local Zotero instance? That
is, it would be nice if I did not have to use one API to get a
formatted citation from zotero.org and another to get a formatted
citation from a local browser instance.

best, Erik

1. http://e6h.org/~egh/hg/zotero-plain/
2. http://docutils.sourceforge.net/rst.html

Bruce D'Arcus

unread,
Dec 9, 2010, 12:17:33 PM12/9/10
to zoter...@googlegroups.com

The same problems we've been discussing around document portability for ages ;-)

Bruce

Dan Stillman

unread,
Dec 9, 2010, 12:56:11 PM12/9/10
to zoter...@googlegroups.com

I don't think that has much to do with this discussion.

Bruce D'Arcus

unread,
Dec 9, 2010, 1:00:51 PM12/9/10
to zoter...@googlegroups.com

Can I cite an item by URL or DOI and get back a formatted reference
from the service?

Bruce

Alf Eaton

unread,
Dec 10, 2010, 10:42:31 AM12/10/10
to zotero-dev
On Dec 8, 9:54 pm, Dan Stillman <dstill...@zotero.org> wrote:
> We're pleased to announce that it's now possible to generate formatted
> references via the Zotero API.
>
> Updated documentation is available athttp://www.zotero.org/support/dev/server_api
>
> We've implemented a node.js-based wrapper around Frank Bennett's
> excellent citeproc-js CSL processor (which is also used in Zotero 2.1)
> and are using it as a backend service. We'll be checking in the code for
> that service tohttps://www.zotero.org/svn/citeproc-node/trunk/soon.
> The data server generates citeproc-js JSON for requested items and
> passes it to citeproc-node.
>
> There are currently two possible bibliographic modes, format=bib and
> content=bib:
>
> format=bib will return a formatted bibliography as XHTML with inline
> CSS. For performance reasons—with the API, not with citeproc-js—this is
> currently limited to 150 items. Any more will return an error. The
> returned XHTML is not currently marked up with RDFa or COinS (here or in
> the client), but that's one thing we'll be looking to add.

Nice :-) Looking forward to trying this locally when it's released -
and maybe adding COinS support, too.

alf

Erik Hetzner

unread,
Dec 29, 2010, 9:56:05 PM12/29/10
to zoter...@googlegroups.com
At Wed, 08 Dec 2010 16:54:42 -0500,
Dan Stillman wrote:
>
> We're pleased to announce that it's now possible to generate formatted
> references via the Zotero API.
>
> […]
>
> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?format=bib&style=chicago-note-bibliography
>
> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?content=bib&style=apa

Hi,

These work great, but I can’t seem to get this to work:

https://api.zotero.org/users/<userID>/items/<itemKey>?format=bib&key=XXX

Using content=bib does work, however:

https://api.zotero.org/users/<userID>/items/<itemKey>?content=bib&key=XXX

Is this a bug, or am I doing something wrong?

Dan also stated:

> We're considering supporting usernames directly in API requests.

Is there any progress on this? I am happy to use userids for
zotero-plain [1], though I think user names look nicer.

Dan Stillman

unread,
Jan 5, 2011, 2:31:35 PM1/5/11
to zoter...@googlegroups.com
On 12/29/10 9:56 PM, Erik Hetzner wrote:
> At Wed, 08 Dec 2010 16:54:42 -0500,
> Dan Stillman wrote:
>> We're pleased to announce that it's now possible to generate formatted
>> references via the Zotero API.
>>
>> [�]
>>
>> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?format=bib&style=chicago-note-bibliography
>>
>> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?content=bib&style=apa
> These work great, but I can�t seem to get this to work:

>
> https://api.zotero.org/users/<userID>/items/<itemKey>?format=bib&key=XXX

format=bib should now work for individual items. Thanks.

> Dan also stated
>> We're considering supporting usernames directly in API requests.
> Is there any progress on this? I am happy to use userids for
> zotero-plain [1], though I think user names look nicer.

Not yet.

Olivier Cailloux

unread,
Jan 7, 2011, 11:28:41 AM1/7/11
to zoter...@googlegroups.com
Dan Stillman a �crit :

> We're pleased to announce that it's now possible to generate formatted
> references via the Zotero API.
Good news! I guess that will help me achieving this:
http://forums.zotero.org/discussion/15640/unattended-export-through-a-script/
(namely, retrieval of bibtex-formatted references). Thinking about it I
still would like to try implementing it even if experimental... (Don't
hesitate to comment on that thread on how and where to start if any
advice seems appropriate.)
> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?format=bib&style=chicago-note-bibliography
>
> https://api.zotero.org/groups/1/collections/42ZCTF3U/items?content=bib&style=apa
>
Excuse the silly question, but what login information should I use to
access these examples? I tried my normal zotero account, to no avail.
Olivier
>
> - Dan
>

fcheslack

unread,
Jan 7, 2011, 12:08:12 PM1/7/11
to zoter...@googlegroups.com
> Excuse the silly question, but what login information should I use to access
> these examples? I tried my normal zotero account, to no avail.
> Olivier

Just try reloading it. Browsers sometimes ask for basic auth on api
feeds when none is required, but libraries making requests to the api
will not have any problems (nor should browsers most of the time).

Olivier Cailloux

unread,
Jan 7, 2011, 1:06:49 PM1/7/11
to zoter...@googlegroups.com
fcheslack a écrit :
Ok, thanks. Seems like FF thinks I want a bookmark when I insist, I don't know if that's expected but anyway I'll rather experiment with wget.

I have further questions but I don't want to spam this list too much so please have a look at the forum if you have some time: http://forums.zotero.org/discussion/15640/unattended-export-through-a-script/ .
Olivier

Reply all
Reply to author
Forward
0 new messages