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:

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:

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:

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:

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.

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:

# 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.

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:

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:

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

Per-Client:

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:

# 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:

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:

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:

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

# 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:

# 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:

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:

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:

# 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:

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:

# 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:

# 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:

# 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:

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:

# .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:

# 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:

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

DEFAULT_TOKEN

Default token value (nil):

Monday::Configuration::DEFAULT_TOKEN
# => nil

DEFAULT_VERSION

Default API version:

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

DEFAULT_OPEN_TIMEOUT

Default connection timeout in seconds:

Monday::Configuration::DEFAULT_OPEN_TIMEOUT
# => 10

DEFAULT_READ_TIMEOUT

Default read timeout in seconds:

Monday::Configuration::DEFAULT_READ_TIMEOUT
# => 30

CONFIGURATION_FIELDS

Array of valid configuration field names:

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

External References

Edit this page

Last updated 5 hours ago

Was this page helpful?