# 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](https://www.zotero.org/support/dev/web_api/v3/basics#user_and_group_library_urls) 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`

{% hint style="info" %}
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 !
{% endhint %}

### `params` : filtering your items

The **params** can apply search parameters & filters to your request. Refer to the [official API documentation](https://www.zotero.org/support/dev/web_api/v3/basics#read_requests) 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](https://www.zotero.org/support/dev/web_api/v3/basics#search_parameters).

### :pencil2: Examples

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

```javascript
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

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