This is a Ruby wrapper for redbooth's API.
We use YARD for documentation.
First, you've to install the gem
gem install redbooth-rubyand 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_'
endin 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.
Redbooth oauth2 API documentation
using omniauth? đź‘Ť good choice, just try this gem
not using omniauth,? no prob oauth implementation comming soon
...
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)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:
-
202status code -
Retry-Afterheader 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) })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:Arrayof elements in the current page -
count:Integernumber of the total elements -
current_page:Integercurrent page number (nil if the resource is not paginated) -
total_pages:Integertotal pages number (nil if the resource is not paginated) -
next_page:RedboothRuby::Request::CollectionCollection object pointing to the next page (nil if the resource is not paginated or there is no next page) -
prev_page:RedboothRuby::Request::CollectionCollection object pointing to the prev page (nil if the resource is not paginated or there is no next page)
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!List users in your network
users_collection = client.user(:index)
users = users_collection.allFetch a specific user
user = client.user(:show, id: 123)Lists task lists in your visibility scope
tasklists_collection = client.task_list(:index)
tasklists = tasklists_collection.allYou 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)Lists tasks in your visibility scope
tasks_collection = client.task(:index)
tasks = tasks_collection.allYou 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)Lists organizations in your visibility scope
organization_collection = client.organization(:index)
organizations = organization_collection.allYou 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)Lists projects in your visibility scope
project_collection = client.project(:index)
projects = project_collection.allYou 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 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.allYou 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 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.allYou 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)Lists conversations in your visibility scope
conversation_collection = client.conversation(:index)
conversations = conversation_collection.allYou 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 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.allYou 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)Lists notes in your visibility scope
notes_collection = client.note(:index)
notes = notes_collection.allYou 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 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.allYou 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 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.allYou 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 }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*')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.metadataUpdate 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')Copyright (c) 2012-2013 Redbooth. See LICENSE for details.