ruby-box

Build Status:

Mainted by: Attachments.me

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 directorydetailed_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 efficientdiscussion=folder.discussions.firstdiscussion.comments.each{|comment| pcomment.message}

• Creating a shared link for a folder.

folder=client.folder('image_folder').create_shared_link# lookups by id are more efficientpfolder.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 efficientfile=client.file(@file_id)pfile.namepfile.created_at

• Uploading a file to a folder.

file=client.upload_file('./LICENSE.txt','/license_folder')# lookups by id are more efficientfile=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 efficientf.close()# You can also grab the raw url withclient.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# thisclient.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 efficientcomments=client.file_by_id(@file_id).commentscomments.eachdo |comment|
pcomment.messageend

• Creating a shared link for a file.

file=client.file('/image_folder/an-image.jpg').create_shared_linkfile=client.file_by_id(@file_id).create_shared_link# using an idpfile.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 efficientfile=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 efficientfile=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')# pathfile=client.file_by_id(@file_id)# idcomment=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.eachdo |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_responseeresp.chunk_sizeeresp.next_stream_positioneresp.events.eachdo |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

Copyright

Copyright (c) 2012 Attachments.me. See LICENSE.txt for further details.