Configuration

Manage global and client-specific configuration for the monday_ruby gem.

Overview

The Monday::Configuration class controls how the gem connects to the monday.com API. You can set configuration globally for all clients or customize it per-client instance.

Configuration Options

All configuration options with their types, defaults, and descriptions:

Option	Type	Default	Description
`token`	String	`nil`	API authentication token (required for all requests)
`host`	String	`"https://api.monday.com/v2"`	monday.com API endpoint URL
`version`	String	`"2023-07"`	API version to use (format: YYYY-MM)
`open_timeout`	Integer	`10`	Seconds to wait for connection to open
`read_timeout`	Integer	`30`	Seconds to wait for response data

Global Configuration

Configure once and use across all clients:

ruby

require "monday_ruby"

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.version = "2024-10"
  config.open_timeout = 15
  config.read_timeout = 60
end

# All clients use global configuration
client = Monday::Client.new
response = client.boards

When to Use Global Configuration

Use global configuration when your application uses a single monday.com account. This is the most common scenario.

Accessing Global Config

Read global configuration values:

ruby

Monday.configure do |config|
  config.token = "my_token"
  config.version = "2024-10"
end

# Access global config
puts Monday.config.token    # => "my_token"
puts Monday.config.version  # => "2024-10"
puts Monday.config.host     # => "https://api.monday.com/v2"

Instance Configuration

Configure individual clients with different settings:

ruby

require "monday_ruby"

# Client A with token A
client_a = Monday::Client.new(
  token: ENV["MONDAY_TOKEN_A"],
  version: "2024-10"
)

# Client B with token B and longer timeouts
client_b = Monday::Client.new(
  token: ENV["MONDAY_TOKEN_B"],
  version: "2024-01",
  read_timeout: 120
)

# Each client uses its own configuration
response_a = client_a.boards
response_b = client_b.boards

When to Use Instance Configuration

Use instance configuration for multi-tenant applications or when connecting to multiple monday.com accounts simultaneously.

Accessing Instance Config

Read instance-specific configuration:

ruby

client = Monday::Client.new(
  token: "my_token",
  version: "2024-10"
)

# Access client's config
puts client.config.token    # => "my_token"
puts client.config.version  # => "2024-10"

Methods

initialize

Creates a new configuration instance with optional parameters.

ruby

config = Monday::Configuration.new(
  token: "your_token",
  version: "2024-10",
  open_timeout: 15,
  read_timeout: 60
)

Parameters:

token (String, optional) - API authentication token
host (String, optional) - API endpoint URL
version (String, optional) - API version
open_timeout (Integer, optional) - Connection timeout in seconds
read_timeout (Integer, optional) - Response timeout in seconds

Raises:

ArgumentError - When invalid configuration keys are provided

Example:

ruby

# Valid configuration
config = Monday::Configuration.new(token: "abc123")

# Invalid configuration (raises ArgumentError)
config = Monday::Configuration.new(invalid_key: "value")
# => ArgumentError: Unknown arguments: [:invalid_key]

reset

Resets all configuration values to their defaults.

ruby

Monday.configure do |config|
  config.token = "my_token"
  config.version = "2024-10"
end

Monday.config.reset

puts Monday.config.token   # => nil
puts Monday.config.version # => "2023-07"

Note: This method is typically used in test environments to ensure clean state between tests.

Attribute Accessors

All configuration fields have getter and setter methods:

ruby

config = Monday::Configuration.new

# Setters
config.token = "new_token"
config.version = "2024-10"
config.host = "https://custom.monday.com/v2"
config.open_timeout = 20
config.read_timeout = 90

# Getters
config.token        # => "new_token"
config.version      # => "2024-10"
config.host         # => "https://custom.monday.com/v2"
config.open_timeout # => 20
config.read_timeout # => 90

API Versions

The version parameter specifies which monday.com API version to use.

Available Versions

monday.com uses dated API versions in YYYY-MM format:

"2024-10" - October 2024 version
"2024-01" - January 2024 version
"2023-10" - October 2023 version
"2023-07" - July 2023 version (default)

Setting API Version

Global:

ruby

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.version = "2024-10"
end

Per-Client:

ruby

client = Monday::Client.new(
  token: ENV["MONDAY_TOKEN"],
  version: "2024-10"
)

Version Usage

The version is sent in the API-Version header with every request:

ruby

# Internally, requests include:
# Headers:
#   Authorization: your_token
#   API-Version: 2024-10

Breaking Changes

API versions may introduce breaking changes. Test thoroughly before upgrading to a new version.

Finding Available Versions

See monday.com's API versioning documentation for the complete list of available versions and their changes.

Timeouts

Control how long the gem waits for API responses.

open_timeout

Maximum seconds to wait while establishing a connection to monday.com's API.

Default: 10 seconds

When to Increase:

Slow network connections
Connecting through proxies
High-latency environments

Example:

ruby

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.open_timeout = 20  # Wait up to 20 seconds to connect
end

read_timeout

Maximum seconds to wait for the API to return a response after the connection is established.

Default: 30 seconds

When to Increase:

Large data exports
Complex queries with many boards/items
Bulk operations
Known slow endpoints

Example:

ruby

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.read_timeout = 120  # Wait up to 2 minutes for response
end

Timeout Behavior

When a timeout is exceeded, a timeout error is raised:

ruby

client = Monday::Client.new(
  token: ENV["MONDAY_TOKEN"],
  read_timeout: 5  # Very short timeout
)

begin
  # Large query that takes more than 5 seconds
  response = client.boards.query(
    args: { limit: 1000 },
    select: ["id", "name", "items { id name }"]
  )
rescue Net::ReadTimeout => e
  puts "Request timed out: #{e.message}"
  # Retry with longer timeout or smaller query
end

Usage Examples

Development Environment

ruby

# config/initializers/monday.rb (Rails)
# or at the top of your script

require "dotenv/load"

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.version = "2024-10"
  config.read_timeout = 60  # Longer timeout for complex queries
end

Production Environment

Using Rails Credentials:

ruby

# config/initializers/monday.rb
Monday.configure do |config|
  config.token = Rails.application.credentials.monday[:token]
  config.version = Rails.application.credentials.monday[:version] || "2024-10"
  config.open_timeout = 15
  config.read_timeout = 90
end

Using Environment Variables:

ruby

Monday.configure do |config|
  config.token = ENV.fetch("MONDAY_TOKEN")
  config.version = ENV.fetch("MONDAY_API_VERSION", "2024-10")
  config.open_timeout = ENV.fetch("MONDAY_OPEN_TIMEOUT", 10).to_i
  config.read_timeout = ENV.fetch("MONDAY_READ_TIMEOUT", 30).to_i
end

Multi-Tenant Application

Handle multiple monday.com accounts:

ruby

class MondayService
  def initialize(user)
    @client = Monday::Client.new(
      token: user.monday_token,
      version: user.monday_api_version || "2024-10"
    )
  end

  def fetch_boards
    @client.boards.query(
      select: ["id", "name", "workspace_id"]
    )
  end
end

# Usage
service = MondayService.new(current_user)
response = service.fetch_boards

Testing Environment

Reset configuration between tests:

ruby

# spec/spec_helper.rb or test/test_helper.rb
RSpec.configure do |config|
  config.before(:each) do
    Monday.config.reset
    Monday.configure do |c|
      c.token = "test_token"
      c.version = "2024-10"
    end
  end
end

Custom API Host

For testing or custom deployments:

ruby

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.host = "https://staging.monday.com/v2"  # Custom endpoint
  config.version = "2024-10"
end

Custom Host Usage

Changing the host is rarely needed. Only modify this if you're connecting to a custom monday.com deployment or testing environment.

Dynamic Configuration

Change configuration at runtime:

ruby

# Start with default config
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN_DEFAULT"]
end

client = Monday::Client.new

# Later, switch to different account
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN_PREMIUM"]
end

# New clients use updated config
premium_client = Monday::Client.new

Best Practices

Store Tokens Securely

Never hardcode tokens in your source code:

ruby

# Bad - Token in code
Monday.configure do |config|
  config.token = "eyJhbGc..."  # Never do this!
end

# Good - Token from environment
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
end

# Better - Validate token exists
Monday.configure do |config|
  config.token = ENV.fetch("MONDAY_TOKEN") do
    raise "MONDAY_TOKEN environment variable not set"
  end
end

Use Environment-Specific Configuration

Separate configuration by environment:

ruby

# config/initializers/monday.rb
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]

  case Rails.env
  when "development"
    config.read_timeout = 120  # Longer timeout for debugging
  when "test"
    config.token = "test_token"
  when "production"
    config.open_timeout = 10
    config.read_timeout = 60
    config.version = "2024-10"
  end
end

Validate Configuration on Startup

Ensure configuration is valid before running:

ruby

def validate_configuration!
  raise "MONDAY_TOKEN not configured" if Monday.config.token.nil?

  client = Monday::Client.new
  response = client.account.query(select: ["id"])

  unless response.success?
    raise "Invalid monday.com configuration: #{response.code}"
  end

  puts "monday.com configuration valid"
end

# Call during application startup
validate_configuration!

Document Configuration Requirements

Add a .env.example file to your project:

bash

# .env.example
# monday.com API Configuration
MONDAY_TOKEN=your_token_here
MONDAY_API_VERSION=2024-10
MONDAY_READ_TIMEOUT=60

Use Defaults When Appropriate

Only override defaults when necessary:

ruby

# Minimal configuration (uses defaults for everything else)
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
end

# Override only what you need
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.read_timeout = 120  # Only change this
end

Constants

DEFAULT_HOST

Default monday.com API endpoint:

ruby

Monday::Configuration::DEFAULT_HOST
# => "https://api.monday.com/v2"

DEFAULT_TOKEN

Default token value (nil):

ruby

Monday::Configuration::DEFAULT_TOKEN
# => nil

DEFAULT_VERSION

Default API version:

ruby

Monday::Configuration::DEFAULT_VERSION
# => "2023-07"

DEFAULT_OPEN_TIMEOUT

Default connection timeout in seconds:

ruby

Monday::Configuration::DEFAULT_OPEN_TIMEOUT
# => 10

DEFAULT_READ_TIMEOUT

Default read timeout in seconds:

ruby

Monday::Configuration::DEFAULT_READ_TIMEOUT
# => 30

CONFIGURATION_FIELDS

Array of valid configuration field names:

ruby

Monday::Configuration::CONFIGURATION_FIELDS
# => [:token, :host, :version, :open_timeout, :read_timeout]

Client - Client initialization and usage
Authentication - Token management and security
Installation - Initial setup
Error Handling - Handling configuration errors

Configuration ​

Overview ​

Configuration Options ​

Global Configuration ​

Accessing Global Config ​

Instance Configuration ​

Accessing Instance Config ​

Methods ​

initialize ​

reset ​

Attribute Accessors ​

API Versions ​

Available Versions ​

Setting API Version ​

Version Usage ​

Finding Available Versions ​

Timeouts ​

open_timeout ​

read_timeout ​

Timeout Behavior ​

Usage Examples ​

Development Environment ​

Production Environment ​

Multi-Tenant Application ​

Testing Environment ​

Custom API Host ​

Dynamic Configuration ​

Best Practices ​

Store Tokens Securely ​

Use Environment-Specific Configuration ​

Validate Configuration on Startup ​

Document Configuration Requirements ​

Use Defaults When Appropriate ​

Constants ​

DEFAULT_HOST ​

DEFAULT_TOKEN ​

DEFAULT_VERSION ​

DEFAULT_OPEN_TIMEOUT ​

DEFAULT_READ_TIMEOUT ​

CONFIGURATION_FIELDS ​

Related Documentation ​

External References ​

Configuration

Overview

Configuration Options

Global Configuration

Accessing Global Config

Instance Configuration

Accessing Instance Config

Methods

initialize

reset

Attribute Accessors

API Versions

Available Versions

Setting API Version

Version Usage

Finding Available Versions

Timeouts

open_timeout

read_timeout

Timeout Behavior

Usage Examples

Development Environment

Production Environment

Multi-Tenant Application

Testing Environment

Custom API Host

Dynamic Configuration

Best Practices

Store Tokens Securely

Use Environment-Specific Configuration

Validate Configuration on Startup

Document Configuration Requirements

Use Defaults When Appropriate

Constants

DEFAULT_HOST

DEFAULT_TOKEN

DEFAULT_VERSION

DEFAULT_OPEN_TIMEOUT

DEFAULT_READ_TIMEOUT

CONFIGURATION_FIELDS

Related Documentation

External References