R API for Trello

Fetching specific models

trelloR includes a number of data-fetching functions each of which targets one single model. This puts certain limits on what you can ask for; on the other hand, it eliminates most of the effort (and makes the code easier to read). It also means that the functions can have predictable names which are easy to guess. For example:

• call get_board_cards() to obtain cards from a particular board
• call get_card_members() to obtain the list of people assigned to a card

Basically, the parent model is always followed by the child model with the get_ prefix in the beginning. For an overview of the available functions, call ?get_board, ?get_card, ?get_team, ?get_member, get_list or ?get_id.

Searching for model ID

Sometimes you don’t know the model ID but you have other information, such as name, description or other text. In such cases, you can call trello_search(), which is equivalent to the search field in Trello web app. To limit your search to specific models (e.g. only members), call the appropriately named version of the search function:

captain = trello_search_members("Captain America", token = my_token)

Searches need to be authorized; hence, the token argument is needed (see Getting private data).

Custom requests with trello_get()

Most of the functions in this package are wrappers for trello_get(). You can call it directly if you lack a particular data-fetching option, or you can define a new function by wrapping trello_get() and providing some default values.

The following example creates a function that fetches all updates made in a given card (it uses a filter because updates are a type of action, and there’s no need to retrieve all actions):

get_card_updates = function(id, ...) {
    trello_get(parent = "card", child  = "actions", id = id, filter = "updateCard", ...)
}

Such functions can be called the usual way by supplying a card ID:

idc = cards$id[1]
card_updates = get_card_updates(idc, limit = 5)
#> Sending request...
#> Request URL:
#> https://api.trello.com/1/card/57bc9cdff5ceb056e765b915/actions?filter=updateCard&limit=5
#> Received 2 results
#> Returning tbl_df tbl data.frame

For a detailed list of all possible queries, consult the Trello API reference.

Additional arguments for trello_get()

• token is necessary for accessing private boards (see Getting private data); defaults to NULL
• limit defaults to 1000 results; this is also the maximum number of results for a single request
• query is useful if you need to provide a list of key-value pairs, such as query = list(key1 = "value1", key2 = "value2"); these will get appended to the URL request. Setting filter = "updateCard" and limit=10 is equivalent to query = list(filter = "updateCard", limit = 10); if you need more information about keys and values are available, refer to Trello API reference
• paging is useful for requests that return more than 1000 results; it breaks the request down into smaller pieces, each of which returns no more than 1000 results. Defaults to FALSE, but if the request returns 1000 results, paging is suggested by a message in the console
• bind.rows binds all pages into a single data.frame; defaults to TRUE

If bind.rows = FALSE, the result will be a list with as many elements as there are pages. This is also a fallback option for the rare occasion when the responses are not perfectly formatted and make dplyr::bind_rows fail.

When calling trello_get() directly, you have an option to either specify parent and child or provide the whole URL as a character vector of length 1.

board_comments = trello_get(parent = "board", child = "actions", id = idb,
                            filter = "commentCard", limit = 5)
#> Sending request...
#> Request URL:
#> https://api.trello.com/1/board/4d5ea62fd76aa1136000000c/actions?filter=commentCard&limit=5
#> Received 5 results
#> Returning tbl_df tbl data.frame

Error handling

If a request fails because of the client-side or server-side error, the error code is reprinted in the console. Additional server messages are also included to make debugging easier. See the example with invalid card ID below:

tryCatch(
    expr  = get_card_actions(id = "I_have_a_bad_feeling_about_this"),
    error = function(e) {
        print(e$message)})
#> Sending request...
#> Request URL:
#> https://api.trello.com/1/card/I_have_a_bad_feeling_about_this/actions?limit=1000
#> [1] "Client error: (400) Bad Request : invalid id"

In case of a server-side error, the request will be re-send two more times, with 1.5s delay before each attempt. If it fails for the 3rd time, the error message is printed in the console.

Using the token to retrieve private data

One thing you can do immediately after obtaining the token is call get_my_boards() to get an overview of your boards. It accepts the token as its only argument and returns a data.frame with the board names and IDs related to the user who authorized the app.

my_boards = get_my_boards(my_token)

sessionInfo()
#> R version 3.3.1 (2016-06-21)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: elementary OS Freya
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=cs_CZ.UTF-8        LC_COLLATE=C              
#>  [5] LC_MONETARY=cs_CZ.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=cs_CZ.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=cs_CZ.UTF-8 LC_IDENTIFICATION=C       
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] trelloR_0.1.0 httr_1.2.1   
#> 
#> loaded via a namespace (and not attached):
#>  [1] Rcpp_0.12.6     digest_0.6.10   dplyr_0.5.0     assertthat_0.1 
#>  [5] R6_2.1.3        jsonlite_1.1    DBI_0.4-1       formatR_1.4    
#>  [9] magrittr_1.5    evaluate_0.9    stringi_1.1.1   curl_2.0       
#> [13] rmarkdown_1.0   tools_3.3.1     stringr_1.0.0   yaml_2.1.13    
#> [17] htmltools_0.3.5 knitr_1.13      tibble_1.0