Redbooth-Ruby

This is a Ruby wrapper for redbooth's API.

Documentation

We use YARD for documentation.

Usage

First, you've to install the gem

gem install redbooth-ruby

and require it

require 'redbooth-ruby'

and set up your app credentials

RedboothRuby.config do |configuration|
  configuration[:consumer_key] = '_your_consumer_key_'
  configuration[:consumer_secret] = '_your_consumer_secret_'
end

in fact this last step is optional (yes! we support multiple applications) but if as most fo the humans you use only one redbooth app, this is the easyest way to go.

Oauth

Redbooth oauth2 API documentation

using omniauth? 👍 good choice, just try this gem

teambox/omniauth-redbooth

not using omniauth,? no prob oauth implementation comming soon

...

Client

Everything starts with the client, once you have the user credentials you should create a session and a client to start interaction with the API

session = RedboothRuby::Session.new(
  token: '_your_user_token_'
)
client = RedboothRuby::Client.new(session)

Now you can perform any user api call inside the clien wrapper

client.me(:show)

If you have multiple applications or you just want to ve explicit use the application credentials inside the session creation

session = RedboothRuby::Session.new(
  token: '_your_user_token_',
  consumer_key: '_your_app_key_',
  consumer_secret: '_your_app_secret'
)
client = RedboothRuby::Client.new(session)

Refresh Token

By default, your access token will expires in 7200 seconds (2 hours). If you want to automatically get a new one, just need to provide the refresh_token param

session = RedboothRuby::Session.new(
  token: '_your_user_token_',
  refresh_token: '_your_user_refresh_token_',
  auto_refresh_token: true
)

You can also provide a callback to get the new access token:

session = RedboothRuby::Session.new(
  token: '_your_user_token_',
  refresh_token: '_your_user_refresh_token_',
  auto_refresh_token: true,
  on_token_refresh: Proc.new do |old_access_token, new_access_token|
    auth = Authentication.where(access_token: old_access_token.token).first
    auth.access_token = new_access_token.token
    auth.refresh_token = new_access_token.refresh_token
    auth.save
  end
)

Async Endpoints

Redbooth API is ready to transform any endpoint to async performing in order to optimize the API response time. When this happens the response will contain:

• 202 status code

• Retry-After header with the time in seconds to wait until retry the same request

To know the real response of this request you just need to perform the same request once the retry-after time passed.

In the client we handle this work for you by waiting and repeating the request if needed, but if you want to perform the retry method in any other way (renqueue the job for instance) you should declare it in the client initialize process:

client = RedboothRuby::Client.new(session, retry: -> { |time|  YourFancyJob.enque_in(time, params) })

Collections

Index methods always return a RedboothRuby::Request::Collection object to handle the pagination and ordering.

ie:

tasks_collection = client.task(:index, project_id: 2)
tasks_collection.class # => RedboothRuby::Request::Collection
tasks = tasks_collection.all

tasks_collection.current_page # => 1
tasks_collection.total_pages # => 7
tasks_collection.per_page # => 30
tasks_collection.count # => 208

next_page_collection = tasks_collection.next_page
next_page_collection.class # => RedboothRuby::Request::Collection

prev_page_collection = tasks_collection.prev_page
prev_page_collection.class # => RedboothRuby::Request::Collection

## Collection Methods

• all : Array of elements in the current page

• count : Integer number of the total elements

• current_page: Integer current page number (nil if the resource is not paginated)

• total_pages: Integer total pages number (nil if the resource is not paginated)

• next_page: RedboothRuby::Request::Collection Collection object pointing to the next page (nil if the resource is not paginated or there is no next page)

• prev_page: RedboothRuby::Request::Collection Collection object pointing to the prev page (nil if the resource is not paginated or there is no next page)

Examples

Iterating thought all the pages

tasks_collection = client.task(:index, project_id: 2)
tasks = tasks_collection.all

while task_collection = tasks_collection.next_page do
  tasks << task_collection.all
end

tasks.flatten!

Users

List users in your network

users_collection = client.user(:index)
users = users_collection.all

Fetch a specific user

user = client.user(:show, id: 123)

TaskLists

Lists task lists in your visibility scope

tasklists_collection = client.task_list(:index)
tasklists = tasklists_collection.all

You can also filter by multiple params (see docs here )

filtered_tasklists = client.task_list(:index, order: 'id-DESC',
                                              per_page: 50,
                                              project_id: 123)

Fetch a specific tasklist

tasklist = client.task_list(:show, id: 123)

Update a specific tasklist

tasklist = client.task_list(:update, id: 123, name: 'new name')

Delete a specific tasklist

client.task_list(:delete, id: 123)

Tasks

Lists tasks in your visibility scope

tasks_collection = client.task(:index)
tasks = tasks_collection.all

You can also filter by multiple params (see docs here )

filtered_tasks = client.task(:index, order: 'id-DESC',
                                      per_page: 50,
                                      project_id: 123)

Fetch a specific task

task = client.task(:show, id: 123)

Update a specific task

task = client.task(:update, id: 123, name: 'new name')

Delete a specific task

client.task(:delete, id: 123)

Organizations

Lists organizations in your visibility scope

organization_collection = client.organization(:index)
organizations = organization_collection.all

You can also filter by multiple params (see docs here )

filtered_organizations = client.organization(:index, order: 'id-DESC',
                                                     per_page: 50)

Fetch a specific organization

organization = client.organization(:show, id: 123)

Create a organization

organization = client.organization(:create, name: 'New Organization')

Update a specific organization

organization = client.organization(:update, id: 123, name: 'new name')

Delete a specific organization

client.organization(:delete, id: 123)

Projects

Lists projects in your visibility scope

project_collection = client.project(:index)
projects = project_collection.all

You can also filter by multiple params (see docs here )

filtered_projects = client.project(:index, order: 'id-DESC', per_page: 50)

Fetch a specific project

project = client.project(:show, id: 123)

Create a project

project = client.project(:create, name: 'New Project')

Update a specific project

project = client.project(:update, id: 123, name: 'new name')

Delete a specific project

client.project(:delete, id: 123)

People

People is the redbooth relation between projects and users containing the role information

|-------|         |--------|         |---------|
| User  |   ==>   | Person |   ==>   | Project |
|-------|         |--------|         |---------|
                      \
                    {role}

Lists People in your visibility scope

people_collection = client.person(:index)
people = people_collection.all

You can also filter by multiple params (see docs here )

filtered_people = client.person(:index, order: 'id-DESC', per_page: 50)

Fetch a specific person

people = client.person(:show, id: 123)

Create a person

person = client.person(:create, project_id: 123, user_id: 123, role: 'participant')

Update a specific person

person = client.person(:update, id: 123, role: 'admin')

Delete a specific person

client.person(:delete, id: 123)

Memberships

Memberships is the redbooth relation between organization and users containing the role information

|-------|         |------------|         |--------------|
| User  |   ==>   | Membership |   ==>   | Organization |
|-------|         |------------|         |--------------|
                      \
                    {role}

Lists Memberships in your visibility scope

membership_collection = client.membership(:index)
memberships = membership_collection.all

You can also filter by multiple params (see docs here )

filtered_memberships = client.membership(:index, order: 'id-DESC', per_page: 50)

Fetch a specific membership

memberships = client.membership(:show, id: 123)

Create a membership

membership = client.membership(:create, organization_id: 123, user_id: 123,
  role: 'participant')

Update a specific membership

membership = client.membership(:update, id: 123, role: 'admin')

Delete a specific membership

client.membership(:delete, id: 123)

Conversations

Lists conversations in your visibility scope

conversation_collection = client.conversation(:index)
conversations = conversation_collection.all

You can also filter by multiple params (see docs here )

filtered_conversations = client.conversation(:index, order: 'id-DESC',
                                                     per_page: 50,
                                                     project_id: 123)

Fetch a specific conversation

conversation = client.conversation(:show, id: 123)

Update a specific conversation

conversation = client.conversation(:update, id: 123, name: 'new name')

Delete a specific conversation

client.conversation(:delete, id: 123)

Comments

Comments are the redbooth resources containing the Task and Conversation Content. It also contains the information about the task status changes, assigned changes and due_data changes.

To consume the comments endpoint you allways need to provide a target_type and target_id. This is needed for performance reasons.

Lists comments in your visibility scope

comment_collection = client.comment(:index, target_type: 'task', target_id: 123)
comments = comment_collection.all

You can also filter by multiple params (see docs here )

filtered_comments = client.comment(:index, order: 'id-DESC',
                                           per_page: 50,
                                           project_id: 123,
                                           target_type: 'task',
                                           target_id: 123)

Fetch a specific comment

comment = client.comment(:show, id: 123)

Update a specific comment

comment = client.comment(:update, id: 123, body: 'new body content')

Delete a specific comment

client.comment(:delete, id: 123)

Notes

Lists notes in your visibility scope

notes_collection = client.note(:index)
notes = notes_collection.all

You can also filter by multiple params (see docs here )

filtered_notes = client.note(:index, order: 'id-DESC',
                                     per_page: 50,
                                     project_id: 123)

Fetch a specific note

note = client.note(:show, id: 123)

Update a specific note

note = client.note(:update, id: 123, name: 'new name')

Delete a specific note

client.note(:delete, id: 123)

Subtasks

Subtasks are little sentences under a task that could de resolved or not.

Lists subtasks in your visibility scope. Needs a task_id

subtask_collection = client.subtask(:index, task_id: 123)
subtasks = subtask_collection.all

You can also filter by multiple params (see docs here )

filtered_subtasks = client.subtask(:index, task_id: 123,
                                           order: 'id-DESC',
                                           per_page: 50)

Fetch a specific subtask

subtask = client.subtask(:show, id: 123)

Create a new subtask

subtask = client.subtask(:create, task_id: 123, name: 'new name')

Update a specific subtask

subtask = client.subtask(:update, id: 123, name: 'new name')

Delete a specific subtask

client.subtask(:delete, id: 123)

Files

Files in redbooth could be uploaded or choosen form other service providers (Copy, Dropbox, Gdrive, Box, Signnow, ...). This client allows you to browse or create files in redbooth api.

Lists files in your visibility scope.

files_colilection = client.file(:index)
files = files_collection.all

You can also filter by multiple params (see docs here )

filtered_files_collection = client.file(:index, backend: 'redbooth',
                                                project_id: 123,
                                                order: 'id-DESC',
                                                per_page: 25)

Update a specific file

file = client.file(:update, id: 123, name: 'new_name.doc')

Create a new file

file = File.open('path/to/the/file')
new_file = client.file(:create, project_id: 123,
                                parent_id: nil,
                                backend: 'redbooth',
                                is_dir: false,
                                asset: file )

Delete a specific subtask

client.file(:delete, id: 123)

Download a file

file # RedBoothRuby::File

open('/path/to/your_new_file.txt', 'w') { |f| f.puts file.download }

Search

You can search throught any redbooth entity by using the search method. There is some filter params available:

• query: Regex like query to search

• project_id: Reduce the scope to search for

• target_type: List of entity types to be returned

Search for redbooth objects in your visibility scope

entities = client.search(query: 'task+nothing*')

Metadata

ADVISE: Redbooth metadata API is in Beta status so use this under your own risk.

Metadata API allows you to add custo key value attributes to objects inside redbooth and search by those key value attributes. This is really helpful when doing API syncs or tiny implementations in top of the Redbooth API.

Fetch object metadata

task.metadata

Update object metadata by adding new keys or overwriding the exisiting ones but not touching the others if there is any one.

task.metadata_merge("new_key" => "new value")

Restore user metadata by overwiritng the existing ones.

task.metadata = {"key" => "value"}

Search for a certain metadata key value

metadata_collection = client.metadata(key: 'key', value: 'value', target_type: 'Task')

License

Copyright (c) 2012-2013 Redbooth. See LICENSE for details.