---
title: "Getting public data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting public data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
  
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```

This document explains how to interact with Trello from R with read-only access.
For editing/private access, see [Authorized access](../articles/auth-access.html)
and [Editing functions](../articles/edit-fun.html).

Introduction
------------

Most things in Trello live on a __Board__. A board encapsulates a hierarchy
of resources:  __Members, Teams, Lists, Cards, Custom fields__ and __Actions__.
Some of the resources may contain additional data (e.g. cards may have labels,
due dates etc.) or other nested resources (e.g. boards may have lists, cards,
label definitions etc.)

Each resource can have a parent resource (e.g. a board is a parent resource
for a card) and child resources (a card can include actions as a child resource).
A resource can have more than one parent (a board and a list are both parents
to a card).

To access a resource, you need to know its unique ID, or the ID of its parent
resource. In some cases (e.g. boards or cards), you can use the resource URL
instead.

Getting data
------------

The following snippet fetches 5 cards from the
[trelloR demo board](https://trello.com/b/wVWPK9I4/r-client-for-the-trello-api).
This is a public board and so does not require authentication:

```{r, results='hide'}
library(trelloR)
board = "https://trello.com/b/wVWPK9I4/r-client-for-the-trello-api"
param = list(fields = "id,name,idList,labels")
cards = get_board_cards(board, query = param, limit = 5)
```

The result is a data.frame (or a tibble if installed):

``` {r}
cards[, 1:3]
```

Nested resources can be obtained by querying their parent resource. In the example
above, we didn't have to query each card individually - instead, we just queried
the board resource to get all of its cards.

A general way of retrieving data from a board is to use the function
`get_resource()` which allows you to specify parameters of the query. However,
`trelloR` also includes a number of wrappers for specific resources. For
example: 

* use `get_board_cards()` to get cards from a particular board
* use `get_card_members()` to get a list of people assigned to a card
* use `get_board_fields()` to get custom field definitions
* use `get_card_fields()` to get custom field values
* etc.

The following example creates a wrapper to fetch updates to a given card. This
is represented by the "updateCard" action type passed to `filter`:

```{r, results='hide'}
get_card_updates = function(id, ...) {
  get_resource(parent = "card", child  = "actions", id = id,
               filter = "updateCard", ...)
}
card_updates = get_card_updates(cards[["id"]][4])
```

```{r}
card_updates[, 1:5]
```

Error handling
--------------

If a request fails and`retry.times > 1`, it will be re-attempted. If it fails
after all attempts are spent, the subsequent behavior is determined by the
`on.error` argument.

- If `on.error="stop"`, the request call will throw an error, printing out
  the http status code.
- If `on.error="warn"` or `"message"`, a data frame is returned, containing
  the failed request URL, the error message generated by the API, and response
  headers.
  
```{r, results='hide'}
error = get_card_actions(id = "wrong_id", on.error = "message")
```

```{r}
error
```


__Built with__

```{r}
sessionInfo()
```