Clubhouse API v2 Ruby Gem

This is a resource-oriented ruby library for interacting with the Clubhouse v2 API.

How to use

Initializing the client

require 'clubhouse2'
client = Clubhouse::Client.new(api_key: 'your_api_key')

Quick-start

Queries

Get all stories being followed by a user called 'James'.

client.stories(follower_ids: client.member(name: 'James'))

Get all stories in the 'Testing' project in the 'Completed' state.

client.project(name: 'Testing').stories(workflow_state_id: client.workflow.state(name: 'Completed'))

Get the names of all stories in the 'Testing' project

client.project(name: 'Testing').stories.collect(&:name)

Get all non-archived stories with the label 'Out Of Hours'

client.stories(archived: false, labels: client.label(name: 'Out Of Hours'))

Get all stories last updated more than 30 days ago

client.stories.select { |story| story.updated_at < Date.today - 30 }

Get a list of all story states in the default workflow

client.workflow.states

Creating resources

See the official Clubhouse API documentation for valid properties to use here: https://clubhouse.io/api/rest/v2/

Create a new story in the 'Testing' project

client.project(name: 'Testing').create_story( **...** )
client.create_story(project_id: client.project(name: 'Testing'), **...** )

Updating resources

Updating a property of a resource can be achieved simply by using assignment operators, as shown in the examples below.

See the official Clubhouse API documentation for valid properties to use here: https://clubhouse.io/api/rest/v2/

Change the name of a story

client.story(name: 'Old name').name = 'New name'
client.story(id: 123).name = 'New name'

Add a new follower to a story

client.story(id: 123).follower_ids += [ client.member(name: 'Jeff') ]

Assign a story to an epic

client.story(id: 123).epic_id = client.epic(name: 'Awesome')

Deleting resources

Deletion is possible by using the delete! method, which is available on most resources. Some resources can only be deleted from the web interface.

Delete an epic

client.epic(id: 123).delete!

Delete all stories in the 'Testing' project

client.project(name: 'Testing').stories.each(&:delete!)

Methods returning arrays of resources

	client.projects 					# list all projects
	client.milestones 					# list all milestones
	client.members 						# list all members (users)
	client.epics 						# list all epics
	client.stories 						# list all stories, comments and tasks [WARNING: slow!]
	client.categories 					# list all categories
	client.workflows 					# list all workflows and states
	client.labels 						# list all labels
	client.teams 						# list all teams
	client.story_links					# list all story links

Methods returning single resources

	client.project 						# list the first matching project
	client.milestone 					# list the first matching milestone
	client.member 						# list the first matching member (user)
	client.epic 						# list the first matching epic
	client.story 						# list the first matching story [WARNING: slow!]
	client.category 					# list the first matching category
	client.workflow 					# list the first matching workflow (usually Default)
	client.label 						# list the first matching label
	client.team 						# list the first matching team
	client.story_link 					# list the first matching story link

Creation methods

	client.create_project 					# create a project
	client.create_milestone 				# create a milestone
	client.create_member 					# create a member
	client.create_epic 					# create an epic
	client.create_story 					# create a story
	client.create_category 					# create a category
	client.create_workflow 					# create a workflow
	client.create_label 					# create a label
	client.create_team 					# create a team
	client.create_story_link 				# create a story link
	client.story.create_comment				# create a comment for a story
	client.story.create_task				# create a task for a story
	client.epic.create_comment				# create a comment for an epic

Update methods

	client.update_project 					# update a project
	client.update_milestone 				# update a milestone
	client.update_member 					# update a member
	client.update_epic 					# update an epic
	client.update_story 					# update a story
	client.update_category 					# update a category
	client.update_workflow 					# update a workflow
	client.update_label 					# update a label
	client.update_team 					# update a team
	client.update_story_link 				# update a story link

Filtering

It's possible to filter by any resource property provided by the API. Multiple property filters can be specified. Filters match any member of an array, for example you can filter stories by follower_ids, which will match any stories for which the given member, or members, are followers.

	client.project(id: 123)			# get a specific project
	client.project(name: 'blah')		# get a project by name
	client.projects(archived: true) 	# get all archived projects
	client.project(id: 123).stories		# get stories belonging to a project
	client.story(archived: false)		# get all non-archived stories

Notes

Note that querying for stories is quicker when performed on a Project, rather than using the client.projects method. This is because stories are only available as children of a project, so building the global story array requires making an API call to every project.