get_resource: Get Data From Trello API

In trelloR: Access the Trello API

Get Data From Trello API

Description

Fetch resources using Trello API.

Usage

get_resource(
  parent = NULL,
  child = NULL,
  id = NULL,
  token = NULL,
  query = NULL,
  url = NULL,
  filter = NULL,
  limit = 100,
  on.error = c("stop", "warn", "message"),
  retry.times = 1,
  handle = NULL,
  verbose = FALSE,
  response,
  paging,
  bind.rows
)

Arguments

parent	Parent resource, e.g. "board" or NULL.
child	Child resource, eg. "card" or NULL.
id	Resource ID or NULL.
token	An object of class "Trello_API_token", a path or NULL. If a Token, it is passed as is. If NULL and a cache file called ".httr-oauth" exists, the newest token is read from it. If the file is not found, an error is thrown. If a character vector of length 1, it will be used as an alternative path to the cache file.
query	Named list of key-value pairs, see httr::GET() for details.
url	Url for the GET request. Can be NULL if parent is specified, or a combination of parent, child and id is provided.
filter	Defaults to "all" which includes both open and archived cards or all action types, depending on what resource is requested.
limit	Defaults to 100. Set to Inf to get everything.
on.error	Whether to "stop", "warn" or "message" on API error.
retry.times	How many times to re-try when a request fails. Defaults to 1.
handle	The handle to use with this request, see httr::RETRY().
verbose	Set to TRUE for verbose output.
response, paging, bind.rows	Deprecated.

Value

A data frame with API responses.

Request limits

At maximum, the API can retrieve 1000 results in a single call. Setting limit > 1000 will activate paging. When paging is used, the request will be issued repeatedly, retrieving new batch of results each time until the limit is reached or there is nothing else to fetch. Results are fetched chronologically, ie. newest results are retrieved first (eg. newest cards). Use limit = Inf to make sure you get all.

Errors

If the request fails, server error messages are reprinted on the console. Depending on the value of on.error, the request call can throw an error in R (this is the default), or can issue a warning/message. If the latter, the function returns a data frame containing the failed URL, HTTP status and an informative message (produced by the server).

Results

The API returns JSON objects which are parsed using jsonlite::fromJSON(). Non-JSON results throw an error, but these should never happen anyway. The result is always a data frame, or a tibble if the package is installed.

Filter

Both filter and limit exist as explicitly defined arguments, but you can ignore them in favor of supplying their values as query parameters, eg. query = list(filter = "filter_value", limit = "limit_value").

See Also

get_token(), get_id(), httr::GET(), jsonlite::fromJSON()

Examples

# Public boards can be accessed without authorization, so there is no need
# to create a token, just the board id:
url = "https://trello.com/b/wVWPK9I4/r-client-for-the-trello-api"
bid = get_id_board(url)

# Getting resources from the whole board. `filter="all"` fetches archived
# cards as well.
labels = get_board_labels(bid)
cards = get_board_cards(bid, filter = "all")

# It is possible to call `get_resource()` directly:
lists = get_resource(parent = "board", child = "lists", id = bid)

# As with boards, cards can be queried for particular resources, in this case
# to obtain custom fields:
card = cards$id[5]
acts = get_card_fields(card)

# Set `limit` to specify the number of results. Pagination will be used
# whenever limit exceeds 1000. Use `limit=Inf` to make sure you get all.

## Not run: 
all_actions = get_board_actions(bid, limit = Inf)

## End(Not run)

# For private and team boards, a secure token is required:

## Not run: 
key = Sys.getenv("MY_TRELLO_KEY")
secret = Sys.getenv("MY_TRELLO_SECRET")

token = get_token("my_app", key = key, secret = secret,
                  scope = c("read", "write"))

# Token is now cached, no need to pass it explicitly.
cards_open = get_board_cards(board_id, filter = "open")

## End(Not run)

trelloR documentation built on Aug. 28, 2023, 1:07 a.m.