monday_ruby
A Ruby client library for the monday.com GraphQL API. Build integrations with boards, items, columns, and more using idiomatic Ruby.
Features
-
Resource-based API - Clean, intuitive interface (
client.board.query,client.item.create) - Flexible configuration - Global or per-client setup
- Comprehensive error handling - Typed exceptions for different error scenarios
- Cursor-based pagination - Efficiently handle large datasets
- Fully tested - 100% test coverage with VCR-recorded fixtures
Documentation
Installation
Add to your Gemfile:
gem "monday_ruby"Or install directly:
gem install monday_rubyQuick Start
require "monday_ruby"
# Configure with your API token
Monday.configure do |config|
config.token = ENV["MONDAY_TOKEN"]
end
# Create a client
client = Monday::Client.new
# Query boards
response = client.board.query(args: { limit: 5 })
if response.success?
boards = response.body.dig("data", "boards")
boards.each { |board| puts board["name"] }
endGet your API token from your monday.com Admin settings.
Usage
Configuration
Global configuration (recommended):
Monday.configure do |config|
config.token = ENV["MONDAY_TOKEN"]
config.version = "2024-01" # API version (optional)
end
client = Monday::Client.newPer-client configuration:
client = Monday::Client.new(
token: ENV["MONDAY_TOKEN"],
version: "2024-01"
)Configure timeouts:
Monday.configure do |config|
config.token = ENV["MONDAY_TOKEN"]
config.open_timeout = 10 # seconds (default: 10)
config.read_timeout = 30 # seconds (default: 30)
endWorking with Boards
# Query boards
response = client.board.query(
args: { ids: [1234567890] },
select: ["id", "name", "description"]
)
boards = response.body.dig("data", "boards")
# Create a board
response = client.board.create(
args: {
board_name: "Project Tasks",
board_kind: "public",
description: "Track project deliverables"
}
)
board = response.body.dig("data", "create_board")Working with Items
# Create an item
response = client.item.create(
args: {
board_id: 1234567890,
item_name: "Implement authentication",
column_values: {
status: { label: "Working on it" },
date4: { date: "2024-12-31" }
}
}
)
# Query items
response = client.item.query(
args: { ids: [987654321] },
select: ["id", "name", { column_values: ["id", "text"] }]
)
items = response.body.dig("data", "items")Pagination
Handle large datasets efficiently with cursor-based pagination:
# Fetch first page
response = client.board.items_page(
board_ids: 1234567890,
limit: 100
)
items = response.body.dig("data", "boards", 0, "items_page", "items")
cursor = response.body.dig("data", "boards", 0, "items_page", "cursor")
# Fetch next page
if cursor
next_response = client.board.items_page(
board_ids: 1234567890,
limit: 100,
cursor: cursor
)
endSee the Pagination Guide for more details.
Error Handling
The library provides typed exceptions for different error scenarios:
begin
response = client.board.query(args: { ids: [123] })
rescue Monday::AuthorizationError => e
puts "Invalid API token: #{e.message}"
rescue Monday::InvalidRequestError => e
puts "Invalid request: #{e.message}"
rescue Monday::RateLimitError => e
puts "Rate limit exceeded: #{e.message}"
rescue Monday::Error => e
puts "API error: #{e.message}"
endSee the Error Handling Guide for best practices.
Available Resources
The client provides access to all monday.com resources:
-
Boards -
client.board -
Items -
client.item -
Columns -
client.column -
Files -
client.file -
Groups -
client.group -
Updates -
client.update -
Subitems -
client.subitem -
Workspaces -
client.workspace -
Folders -
client.folder -
Account -
client.account -
Activity Logs -
client.activity_log -
Board Views -
client.board_view
For complete API documentation, see the API Reference.
Development
Running Tests
bundle exec rake specTests use VCR to record HTTP interactions, so you don't need a monday.com API token to run them.
Linting
bundle exec rake rubocopAll Checks
bundle exec rake # Runs both tests and linterContributing
Bug reports and pull requests are welcome on GitHub.
Please read our Contributing Guide for details on:
- Development setup and testing
- Documentation guidelines
- Code style and commit conventions
This project follows the Contributor Covenant Code of Conduct.
License
The gem is available as open source under the terms of the MIT License.