ruby-box

Build Status:

RubyBox provides a simple, chainable, feature-rich client for Box's 2.0 API.

Authorization

RubyBox uses Box's OAuth2 Implementaton, Here are the steps involved in authorizing a client:

1) Get the authorization url.

require 'ruby-box'

session = RubyBox::Session.new({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret'
})

authorize_url = session.authorize_url('https://redirect-url-in-app-settings')

2) After redirecting to the authorize_url, exchange the code given for an access_token

@token = session.get_access_token('code-returned-to-redirect_url')
p '@token.token' # the access token.
p '@token.refresh_token' # token that can be exchanged for a new access_token once the access_token expires.

# refreshing token.

session = RubyBox::Session.new({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  access_token: 'original-access-token' 
})

# you need to persist this somehow. the refresh token will change every time you use it
@token = session.refresh_token('your-refresh-token')
save_me_somehow(@token.refresh_token)

3) Create a client using a session initialized with the access_token.

require 'ruby-box'

session = RubyBox::Session.new({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  access_token: 'access-token'
})

client = RubyBox::Client.new(session)

Usage

Once you've created a client, you can start interacting with the Box API. What follows are some basic examples of RubyBox's usage.

Warning

Please note that using a file/folder path is extremely inefficient, as it causes the gem to traverse the directory structure recursively querying each folder in turn. Prefer the _by_id methods where possible for single-request access.

Items

Files and Folders are subclasses of Item. Folder contents (i.e. files and folders inside that folder) are retrieved in a mini-format when the Folder instance is loaded.

There are two caveats to this:

Only some fields are available

a File mini looks like this:

{
    "type": "file",
    "id": "5000948880",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
    "name": "tigers.jpeg"
}

a Folder mini looks like this:

{
    "type":"folder",
    "id":"301415432",
    "sequence_id":"0",
    "name":"my first sub-folder"
}

Requests to fields other than the above (e.g. file.size) will cause a one-off hit to the api, so take care when iterating over folder contents lest a single application method result in hundreds of api hits and take forever to complete.

This can be mitigated by passing a list of extra fields you want to fetch into the .items method:

folder = client.folder_by_id(@folder_id)
# retrieve size, created_at, and description for all items in this directory
detailed_items = folder.items(@item_limit, @offset, ['size', 'created_at', 'description'])

Note: only the type and id fields are included in addition to whatever you specify using the above method, so you must be explicit.

Folders

Listing items in a folder:

files = client.folder('/image_folder').files # all files in a folder using a path.
files = client.folder(@folder_id).files # all files in a folder using an id.
folders = client.root_folder.folders # all folders in the root directory.
files_and_folders = client.folder('files').items # all files and folders in /files

Creating a folder:

client.folder_by_id(@folder_id).create_subfolder('subfolder') # using an id.
client.folder('image_folder').create_subfolder('subfolder') # using a path.

Setting the description on a folder:

folder = client.folder('image_folder') # using a path.
folder.description = 'Description on Folder'
folder.update

Listing the comments in a discussion surrounding a folder.

folder = client.folder('image_folder') # lookups by id are more efficient
discussion = folder.discussions.first
discussion.comments.each {|comment| p comment.message}

Creating a shared link for a folder.

folder = client.folder('image_folder').create_shared_link # lookups by id are more efficient
p folder.shared_link['url'] # https://www.box.com/s/d6de3224958c1755412

Files

Fetching a file's meta information.

file = client.file('/image_folder/an-image.jpg')# lookups by id are more efficient
file = client.file(@file_id)
p file.name
p file.created_at

Uploading a file to a folder.

file = client.upload_file('./LICENSE.txt', '/license_folder') # lookups by id are more efficient
file = client.upload_file_by_folder_id('./LICENSE.txt', @folder_id)

Downloading a file.

f = open('./LOCAL.txt', 'w+')
f.write( client.file('/license_folder/LICENSE.txt').download )
f.close()

# Or you can fetch by file.id, which is more efficient:
f = open('./LOCAL.txt', 'w+')
f.write( client.file_by_id(@file_id).download ) # lookups by id are more efficient
f.close()

# You can also grab the raw url with
client.file_by_id(@file_id).download_url

# Note that this URL is not persistent. Clients will need to follow the url immediately in order to
# actually download the file

Deleting a file.

client.file_by_id(@file_id).delete # this
client.file('/license_folder/LICENSE.txt').delete

Displaying comments on a file.

comments = client.file('/image_folder/an-image.jpg').comments # lookups by id are more efficient
comments = client.file_by_id(@file_id).comments

comments.each do |comment|
    p comment.message
end

Creating a shared link for a file.

file = client.file('/image_folder/an-image.jpg').create_shared_link
file = client.file_by_id(@file_id).create_shared_link # using an id
p file.shared_link.url # https://www.box.com/s/d6de3224958c1755412

Copying a file to another folder.

file = client.file('/one_folder/cow_folder/an-image.jpg')
folder = client.folder('image_folder')

# lookups by id are more efficient

file = client.file_by_id(@file_id)
folder = client.folder_by_id(@folder_id)

file.copy_to(folder)

Moving a file to another folder.

file = client.file('/one_folder/cow_folder/an-image.jpg')
folder = client.folder('image_folder')

# lookups by id are more efficient

file = client.file_by_id(@file_id)
folder = client.folder_by_id(@folder_id)


file.move_to(folder)

Adding a comment to a file.

file = client.file('/image_folder/an-image.jpg') # path
file = client.file_by_id(@file_id) # id
comment = file.create_comment('Hello World!')

Search

You can use RubyBox's search method to return files and folders that match a given query.

items = client.search('image')
items.each do |item|
    p "type=#{item.type} name=#{item.name}"
end

Events

You can use RubyBox's event_response method to return an EventResponse that can be used to process any incoming events.

eresp = client.event_response
eresp.chunk_size
eresp.next_stream_position
eresp.events.each do |ev|
  p "type=#{ev.event_id} type=#{ev.event_type} user=#{ev.created_by.name}"
end

As-User

This must be manually enabled for your account by Box Staff. Contact api@box.com for access. [ More Info ] (http://developers.box.com/docs/#users-as-user)

session = RubyBox::Session.new({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  access_token: 'original-access-token' ,
  as_user: 'your-users-box-id'
})

Users

Current User Info

me = client.me

Current User's enterprise

me = client.me.enterprise

An array of Ruby:Box users in an enterprise (Supports Filtering, Limit and Offset)

users = client.users

Remeber the API filters "name" and "login" by the start of the string. ie: to get "sean+awesome@gmail.com" an approriate filter term would be "sean"

users = client.users("sean" , 10 , 1)

Contributors

full list of contributors

Contributing to ruby-box

RubyBox does not yet support all of Box's API Version 2.0 functionality, be liberal with your contributions.

Rename account.example to account.yml and fill in your Box credentials
Type bundle install
Type rake.. tests should pass
Add a failing test
Make it pass
Submit a pull request

iora-ruby-box

Development

Runtime