boxr: A high-level R interface for the box.com API

Authorization

To use boxr, you need to enable API access for your box.com account. The process is slightly annoying. You only need to do it once - it takes around 2 minutes.

Authorizing from a local computer

1. ‘Create New App’

Go to https://app.box.com/developers/console, (when you are logged in) and click on the button ‘Create New App’, which will guide you through four screens to create your new app.

On the first, select Custom App and click ‘Next’.
On the second, select Standard OAuth 2.0 (User Authentication) and click ‘Next’
On the third, choose a unique name for your app, this can be anything and click ‘Next’
The fourth screen should be a confirmation of successful creation, click ‘View Your App’

Four steps

2. Set OAuth2 Parameters

‘View Your App’ will take you to the Box Developers Console and where you will be in the Configuration sub-menu by default. Scroll down to OAuth 2.0 Redirect URI and set it to http://localhost and be sure to click ‘Save Changes’.

Set Redirect URI

Keep this browser window open because you will need the client_id and client_secret for the next steps back in R.

3. Connect boxr to your account

This means passing your client_id and client_secret to the box_auth function. These strings are not enough for someone to access your account maliciously. However, it’s still a good idea to keep them safe, and out of any files or code which might be shared with others.

Run:

library(boxr)
box_auth()

And paste/type the client_id and client_secret when prompted. If these are valid, a browser window should open, for you to formally grant yourself access to your files at box.com.

4. And you’re done

If box_auth() worked successfully, you won’t need to do any of this again, and thanks to the magic of httr everything should just work. Your client_id and client_secret will be securely stored in your R environment variables, your hashed OAuth2.0 token will stored at ~/.boxr-oauth, .gitignore’d if necessary, and automatically refreshed when needed. If you would like to automatically authenticate each time the package is loaded, consider running box_auth_on_attach(TRUE).

Authorizing from a remote server

Basic operations

Accessing Box directories (folders)

Accessing Box files

Searching Box

Advanced operations

Using Box trash

Interacting with your R session

Basic Operations

Aside from file upload/download, boxr provides functions which mirror base R operations for local files.

box_dl(file_id) and box_ul(file = 'path/to/file') to download and upload files respectively
box_load()/box_save() for remote R workspaces
box_read() to read files straight into R (e.g. .csv or .xlsx files as data.frames)
box_setwd()/box_getwd() to get/set a default box folder
box_source() to read and execute remote code
box_write() to write R objects the remotely hosted files
box_search() to query files stored on box.com
box_add_description() add text descriptions to your files on box.com

Directory wide Operations

Cloud storage services can complement version control systems for code, which aren’t well suited to large binary files (e.g. databases, .RData, or heaps of pdfs). box explicitly versions binary files, keeping old ones, and making it easy fall back to an older copy.

boxr provides git style facilities to upload, download, and synchronize the contents of entire local and remote directories. At the time of writing, the box.com API does not support this directly, and so boxr recursively loops through directory structures.

Synch a whole directory!

box_push will update the remote directory with new/changed local files
box_fetch will update the local directory with new/changed remote files

These functions all have overwrite and delete parameters, which are set to FALSE by default.

Disclaimer: box.com is no replacement for a VCS/remote-database, and familiar verbs are no guarantee of expected behavior! Do check the function documentation before jumping in.

Piping

boxr’s functions have been designed to be ‘pipable’. Here’s a little example:

library(boxr)
library(dplyr)
library(magrittr)

# 'nycflights13.json' is the same as nycflights13::flights, if you want to
# follow along at home

box_auth()

box_search("nycflights13.json") %>%                # Find a remote file
  box_read() %>%                                   # Download it as a data.frame
    group_by(origin, dest, month) %>%              #   Do some, er, cutting edge
    summarise(mu = mean(arr_delay), n = n()) %>%   #   analysis with dplyr!
  box_write("delay_summary.xlsx") %>%              # Convert to .xlsx, upload
  box_add_description("Check out these averages!") # Add a description to your file!

File/Folder IDs

Are how box.com identifies things. You can find them in an item’s URL:

Box folder id

Box file id

Notes

Verbosity

boxr is by default rather verbose, printing status to the console with cat. This is ‘rude’ package behaviour, and may cause unwanted output if used in conjunction with the excellent knitr package.

To supress messages produced using cat, set boxr’s verbose option with:

options(boxr.verbose = FALSE)

Alternatives

boxr aims to expedite data analysis/communication/distribution. Other ways to manipulate a box.com account include:

The box desktop app
The other boxr, written in Ruby. It’s motivations are rather different, and it covers 100% of the box.com API (e.g account administration, etc.)
box themselves provide a wide range of SDKs, including one for Python

Managing your client id & secret

If you don’t like the idea of typing credentials into your console, you can put them straight into ~/.Renviron yourself, prior to the R session:

BOX_CLIENT_ID="youridhere"
BOX_CLIENT_SECRET="yoursecrethere"

(Note the final blank line).

Reporting Bugs

boxr is a realtively new package. If you find anything that looks like a bug while using it, please report it!

The best way to do this is via a GitHub issue, at: https://github.com/brendan-R/boxr/issues

Brendan Rocks

2019-03-03