3.2 Constructing data requests

Using the dataRequests, you can specify one or more requests to be made to the Zotero API. In most cases, you'll be using the same apikey - what will be different is the dataURI argument, and possibly the parameters (params) you want to use.

dataURI : scoping your request

The dataURI tells the API where to look for items ; it's composed of a user-or-group prefix and a suffix.

• The user-or-group prefix will be either users/your_user_id (for a personal library) or groups/the_group_id (for group libraries).

• The suffix is used to specify which items you want within the library. This means both where the items are located, and what kind of items should be retrieved. The official API documentation lists out the possible combinations - it's a great resource !

In most cases, I'd suggest using one of the following :

• All items from your user library : users/your_user_id/items

• All items from one of your collections : users/your_user_id/collections/collection_id/items

You can request either all items or top-level items only. The difference between the two is that top-level items are the items themselves (book, article, paper...), while selecting all items will also return information about attachments & notes.

I suggest asking for all items - it may take longer for the data to be returned, but it'll allow you to open PDFs and import notes directly in Roam !

params : filtering your items

The params can apply search parameters & filters to your request. Refer to the official API documentation for an overview of all that they can do ; within the context of the extension, you likely won't need to specify anything here.

If you don't want to apply any parameters, I highly recommend setting params to a value of limit=100. It's the maximal number of items that can be returned in a single API call ; this will minimize the total number of calls the extension needs to make to get all the items that match a request.

With that said, there are some cases where you might want to use filters, if you have a particular system in Zotero for example. Here are two parameters which you might find helpful :

• itemType will let you scope your request to items of a given type (e.g, papers)

• tag will let you scope your request to items that have/don't have a tag (e.g, papers marked as #read). Logic operators are also available (and, or). Read more in the official docs.

✏️ Examples

Requesting all items in your personal library that are tagged as #read

zoteroRoam_settings = {
    dataRequests: {
        apikey: 'your API key',
        dataURI: 'users/<your_user_id>/items/top',
        params: 'tag=read&limit=100'
    }
}

Requesting all book items from one of your collections

zoteroRoam_settings = {
    dataRequests: {
        apikey: 'your API key',
        dataURI: 'users/<your_user_id>/collections/<the_collection_id>/items',
        params: 'itemType=book&limit=100'
    }
}