Migration Guide: Upgrading to v1.0.0

This guide will help you migrate from monday_ruby v0.x to v1.x. The v1.0.0 release introduces a major architectural change that improves code organization, maintainability, and developer experience.

Overview of Changes

Version 1.0.0 introduces a client-resource architecture that replaces the previous flat API design. This change provides better code organization, more consistent naming conventions, and improved maintainability for future features.

What Changed

Architecture: Moved from a flat API with mixed-in modules to a modular resource class system
Method Access: Resources are now accessed through dedicated resource objects instead of directly on the client
Method Names: Resource methods are now more consistent and predictable
Code Organization: Each resource is encapsulated in its own class with clear responsibilities

Why These Changes Were Made

The v0.x architecture had several limitations:

Poor Separation of Concerns: All resource methods were mixed into the client class, making it bloated
Namespace Pollution: Every resource method was directly accessible on the client, leading to potential naming conflicts
Inconsistent Naming: Method names like create_board, update_item were inconsistent with account (no verb)
Difficult to Extend: Adding new resources required modifying multiple files and careful management of method names
Testing Challenges: Testing individual resources was difficult due to tight coupling

The new architecture solves these problems by:

Encapsulating each resource in its own class
Providing consistent method naming across all resources
Enabling easier testing and maintenance
Following Ruby best practices and modern API design patterns
Setting a foundation for future features like pagination, filtering, and more

Breaking Changes

1. Resource Access Pattern

The most significant change is how you access resources. All resource methods now require accessing the resource object first.

Before (v0.x)

ruby

client = Monday::Client.new(token: "your_token")

# Resources accessed directly on client
response = client.account
response = client.boards
response = client.items

After (v1.x)

ruby

client = Monday::Client.new(token: "your_token")

# Resources accessed through resource objects
response = client.account.query
response = client.board.query
response = client.item.query

2. Method Name Changes

All resource methods have been renamed to be more consistent and predictable.

Account Resource

v0.x	v1.x
`client.account`	`client.account.query`

Board Resource

v0.x	v1.x
`client.boards`	`client.board.query`
`client.create_board`	`client.board.create`
`client.update_board`	`client.board.update`
`client.duplicate_board`	`client.board.duplicate`
`client.archive_board`	`client.board.archive`
`client.delete_board`	`client.board.delete`
`client.delete_board_subscribers`	`client.board.delete_subscribers`

Item Resource

v0.x	v1.x
`client.items`	`client.item.query`
`client.create_item`	`client.item.create`
`client.duplicate_item`	`client.item.duplicate`
`client.clear_item_updates`	`client.item.clear_updates`
`client.move_item_to_group`	`client.item.move_to_group`
`client.archive_item`	`client.item.archive`
`client.delete_item`	`client.item.delete`

Group Resource

v0.x	v1.x
`client.groups`	`client.group.query`
`client.create_group`	`client.group.create`
`client.update_group`	`client.group.update`
`client.duplicate_group`	`client.group.duplicate`
`client.archive_group`	`client.group.archive`
`client.delete_group`	`client.group.delete`

Column Resource

v0.x	v1.x
`client.columns`	`client.column.query`
`client.create_column`	`client.column.create`
`client.change_column_metadata`	`client.column.change_metadata`
`client.change_column_title`	`client.column.change_title`
`client.change_column_value`	`client.column.change_value`
`client.change_multiple_column_values`	`client.column.change_multiple_values`
`client.delete_column`	`client.column.delete`

Workspace Resource

v0.x	v1.x
`client.workspaces`	`client.workspace.query`
`client.create_workspace`	`client.workspace.create`
`client.update_workspace`	`client.workspace.update`
`client.delete_workspace`	`client.workspace.delete`

Update Resource

v0.x	v1.x
`client.create_update`	`client.update.create`
`client.like_update`	`client.update.like`
`client.delete_update`	`client.update.delete`

Subitem Resource

v0.x	v1.x
`client.subitems`	`client.subitem.query`
`client.create_subitem`	`client.subitem.create`

Board View Resource

v0.x	v1.x
`client.board_views`	`client.board_view.query`

Activity Log Resource

v0.x	v1.x
`client.activity_logs`	`client.activity_log.query`

Folder Resource

v0.x	v1.x
`client.folders`	`client.folder.query`
`client.create_folder`	`client.folder.create`
`client.update_folder`	`client.folder.update`
`client.delete_folder`	`client.folder.delete`

Migration Steps

Step 1: Update Your Gemfile

ruby

# Gemfile
gem 'monday_ruby', '~> 1.0'

Run bundle update monday_ruby to install the latest version.

Step 2: Update Resource Access Patterns

Find all instances where you're calling client methods and update them to the new resource pattern.

Search Pattern: Look for client. followed by resource method names like boards, create_board, items, etc.

Example Migration:

ruby

# Before (v0.x)
client = Monday::Client.new(token: token)
boards = client.boards(args: {ids: [123, 456]})
new_board = client.create_board(args: {board_name: "My Board"})

# After (v1.x)
client = Monday::Client.new(token: token)
boards = client.board.query(args: {ids: [123, 456]})
new_board = client.board.create(args: {board_name: "My Board"})

Step 3: Update Method Names

Change all method calls to remove the resource prefix and use the resource object instead.

ruby

# Before (v0.x)
client.create_item(args: {board_id: 123, item_name: "Task"})
client.update_board(args: {board_id: 456, board_name: "Updated"})
client.delete_group(group_id: 789)

# After (v1.x)
client.item.create(args: {board_id: 123, item_name: "Task"})
client.board.update(args: {board_id: 456, board_name: "Updated"})
client.group.delete(group_id: 789)

Step 4: Test Thoroughly

After making changes:

Run your test suite to ensure all API calls work correctly
Test error handling to ensure exceptions are still caught properly
Verify that response objects work as expected (they haven't changed)

Common Migration Scenarios

Scenario 1: Fetching and Creating Boards

ruby

# Before (v0.x)
client = Monday::Client.new(token: token)

# Get all boards
boards = client.boards
boards.body.dig("data", "boards")

# Create a new board
new_board = client.create_board(
  args: {
    board_name: "Project Tracker",
    board_kind: "public"
  }
)

ruby

# After (v1.x)
client = Monday::Client.new(token: token)

# Get all boards
boards = client.board.query
boards.body.dig("data", "boards")

# Create a new board
new_board = client.board.create(
  args: {
    board_name: "Project Tracker",
    board_kind: "public"
  }
)

Scenario 2: Working with Items

ruby

# Before (v0.x)
# Get items from a board
items = client.items(args: {ids: [123, 456]})

# Create a new item
new_item = client.create_item(
  args: {
    board_id: 789,
    item_name: "New Task",
    column_values: {
      status: {label: "Working on it"}
    }
  }
)

# Move item to a different group
client.move_item_to_group(item_id: 123, group_id: "topics")

ruby

# After (v1.x)
# Get items from a board
items = client.item.query(args: {ids: [123, 456]})

# Create a new item
new_item = client.item.create(
  args: {
    board_id: 789,
    item_name: "New Task",
    column_values: {
      status: {label: "Working on it"}
    }
  }
)

# Move item to a different group
client.item.move_to_group(item_id: 123, group_id: "topics")

Scenario 3: Column Value Updates

ruby

# Before (v0.x)
client.change_column_value(
  board_id: 123,
  item_id: 456,
  column_id: "status",
  value: {label: "Done"}
)

client.change_multiple_column_values(
  board_id: 123,
  item_id: 456,
  column_values: {
    status: {label: "Done"},
    person: {personsAndTeams: [{id: 789, kind: "person"}]}
  }
)

ruby

# After (v1.x)
client.column.change_value(
  board_id: 123,
  item_id: 456,
  column_id: "status",
  value: {label: "Done"}
)

client.column.change_multiple_values(
  board_id: 123,
  item_id: 456,
  column_values: {
    status: {label: "Done"},
    person: {personsAndTeams: [{id: 789, kind: "person"}]}
  }
)

Scenario 4: Workspace Management

ruby

# Before (v0.x)
workspaces = client.workspaces
new_workspace = client.create_workspace(args: {name: "Engineering"})
client.update_workspace(workspace_id: 123, args: {name: "Product"})
client.delete_workspace(workspace_id: 456)

ruby

# After (v1.x)
workspaces = client.workspace.query
new_workspace = client.workspace.create(args: {name: "Engineering"})
client.workspace.update(workspace_id: 123, args: {name: "Product"})
client.workspace.delete(workspace_id: 456)

What Stayed the Same

Several aspects of the library remain unchanged to minimize disruption:

1. Configuration

Configuration works exactly the same way in both versions:

ruby

# Global configuration (unchanged)
Monday.configure do |config|
  config.token = "your_token"
  config.version = "2023-07"
end

# Client-specific configuration (unchanged)
client = Monday::Client.new(token: "your_token", version: "2023-07")

2. Response Objects

Response objects have the same interface:

ruby

response = client.board.query

response.success?  # Same as before
response.body      # Same as before
response.status    # Same as before

3. Error Handling

Error handling remains identical:

ruby

begin
  client.board.create(args: {board_name: "Test"})
rescue Monday::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Monday::Error => e
  puts "API error: #{e.message}"
end

4. Method Arguments

The args and select parameters work the same way:

ruby

# Still uses args and select parameters
client.board.query(
  args: {ids: [123, 456]},
  select: ["id", "name", "description"]
)

Common Migration Pitfalls

Pitfall 1: Forgetting the Resource Object

Problem: Calling methods directly on the client

ruby

# This will fail in v1.x
client.boards  # NoMethodError: undefined method `boards'

Solution: Access through the resource object

ruby

# Correct approach
client.board.query

Pitfall 2: Using Old Method Names

Problem: Using the full method name with resource prefix

ruby

# This will fail in v1.x
client.board.create_board  # NoMethodError

Solution: Use the simplified method name

ruby

# Correct approach
client.board.create

Pitfall 3: Inconsistent Resource Names

Problem: Using plural resource names

ruby

# This will fail in v1.x
client.boards.query  # NoMethodError: undefined method `boards'

Solution: All resources are singular

ruby

# Correct approach
client.board.query
client.item.query
client.group.query

Pitfall 4: Assuming Response Format Changed

Problem: Trying to access response differently

ruby

# This still works the same way
response = client.board.query
boards = response.body.dig("data", "boards")  # Unchanged

Solution: Response objects work exactly the same as before

New Features in v1.x

v1.0.0 Features

Enum Support

Version 1.0.0 adds support for GraphQL enums, allowing you to use enum values in your queries:

ruby

# Use enums in your queries
client.board.create(
  args: {
    board_name: "My Board",
    board_kind: :public  # Can use symbols for enums
  }
)

Better Code Organization

The new architecture makes it easier to:

Understand which methods belong to which resource
Add new resources without affecting existing code
Test individual resources in isolation
Navigate the codebase

v1.1.0 Features

If you're migrating directly to v1.1.0, you also get these new features:

Cursor-Based Pagination

Efficiently retrieve large numbers of items using cursor-based pagination:

ruby

# Fetch items with pagination (up to 500 items per page)
response = client.board.items_page(
  board_ids: 123,
  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: 123,
    limit: 100,
    cursor: cursor
  )
end

Configurable Timeouts

Configure connection and read timeouts for API requests:

ruby

Monday.configure do |config|
  config.token = "your_token"
  config.open_timeout = 10  # seconds (default: 10)
  config.read_timeout = 30  # seconds (default: 30)
end

# Or per client
client = Monday::Client.new(
  token: "your_token",
  open_timeout: 15,
  read_timeout: 45
)

Deprecation Warning System

The library now includes a deprecation warning system to help you stay informed about upcoming changes:

ruby

# If you use a deprecated method, you'll see a warning:
client.board.delete_subscribers(...)
# [DEPRECATION] `delete_subscribers` is deprecated and will be removed in v2.0.0.
# Use `client.user.delete_from_board` instead.

Benefits of Upgrading

1. Future-Proof Code

The v1.x architecture is designed to support new monday.com API features with minimal breaking changes. Features like pagination, filtering, and webhooks integrate naturally into the resource pattern.

2. Better Developer Experience

Auto-completion: IDEs can better suggest methods when they're organized by resource
Documentation: Each resource class has clear documentation of its methods
Consistency: Predictable naming makes it easier to guess the correct method name

3. Improved Maintainability

Isolated Resources: Changes to one resource don't affect others
Easier Testing: Resources can be tested independently
Clear Responsibilities: Each class has a single, well-defined purpose

4. Ruby Best Practices

The new architecture follows Ruby community standards and patterns, making the library more familiar to Ruby developers.

Timeline and Support

Version Support Policy

v0.x: No longer actively maintained (security fixes only)
v1.x: Current stable version, receives new features and bug fixes
v2.x: Planned for future, will include removal of deprecated methods

Migration Timeframe

We recommend upgrading to v1.x as soon as possible:

Immediate: Update applications under active development
Within 3 months: Update production applications
Within 6 months: Update all applications (before v2.0.0 deprecations)

Deprecation Timeline

Methods deprecated in v1.1.0 will be removed in v2.0.0:

client.board.delete_subscribers - Use client.user.delete_from_board instead
client.column.column_values - Use client.item.query with column_values select instead

Getting Help

Resources

Documentation: Check the Wiki for detailed API documentation
Changelog: See CHANGELOG.md for all changes
Examples: Browse the examples directory (if available)

Support Channels

Issues: Report bugs or ask questions on GitHub Issues
Discussions: Join conversations on GitHub Discussions
Contributing: See CONTRIBUTING.md for contribution guidelines

Common Questions

Q: Do I need to change my error handling? A: No, error handling remains exactly the same.

Q: Will my existing response parsing code work? A: Yes, response objects have the same interface.

Q: Can I upgrade incrementally? A: No, the v1.0.0 changes are comprehensive. We recommend upgrading all client calls at once.

Q: How long will v0.x be supported? A: v0.x will receive security fixes only. We recommend migrating to v1.x as soon as possible.

Q: Are there any performance differences? A: The architectural changes have minimal performance impact. Response times are virtually identical.

Q: What if I find a bug during migration? A: Please report it on GitHub Issues. We'll prioritize migration-related bugs.

Automated Migration Tools

While we don't provide an automated migration script, you can use these search-and-replace patterns to help with the migration:

Using Regex Find and Replace

Pattern 1: Board methods

Find:    client\.boards\(
Replace: client.board.query(

Find:    client\.create_board\(
Replace: client.board.create(

Find:    client\.update_board\(
Replace: client.board.update(

Find:    client\.delete_board\(
Replace: client.board.delete(

Find:    client\.archive_board\(
Replace: client.board.archive(

Find:    client\.duplicate_board\(
Replace: client.board.duplicate(

Pattern 2: Item methods

Find:    client\.items\(
Replace: client.item.query(

Find:    client\.create_item\(
Replace: client.item.create(

Find:    client\.move_item_to_group\(
Replace: client.item.move_to_group(

Find:    client\.clear_item_updates\(
Replace: client.item.clear_updates(

Pattern 3: Other resources

Find:    client\.account\(
Replace: client.account.query(

Find:    client\.workspaces\(
Replace: client.workspace.query(

Find:    client\.create_workspace\(
Replace: client.workspace.create(

Important: Always review changes manually and test thoroughly after using automated find-and-replace.

Example: Complete Before and After

Here's a complete example showing a typical workflow in both versions:

Before (v0.x)

ruby

require 'monday_ruby'

# Initialize client
client = Monday::Client.new(token: ENV['MONDAY_TOKEN'])

# Get account info
account = client.account
puts "Account: #{account.body.dig('data', 'users', 0, 'account', 'name')}"

# Get all boards
boards = client.boards(args: {limit: 10})
board_id = boards.body.dig('data', 'boards', 0, 'id')

# Create a new item
new_item = client.create_item(
  args: {
    board_id: board_id,
    item_name: "New Task",
    column_values: {
      status: {label: "Working on it"},
      date: {date: "2024-12-31"}
    }
  }
)

item_id = new_item.body.dig('data', 'create_item', 'id')

# Update a column value
client.change_column_value(
  board_id: board_id,
  item_id: item_id,
  column_id: "status",
  value: {label: "Done"}
)

# Create an update
client.create_update(
  item_id: item_id,
  args: {body: "Task completed successfully!"}
)

# Archive the item
client.archive_item(item_id: item_id)

After (v1.x)

ruby

require 'monday_ruby'

# Initialize client (unchanged)
client = Monday::Client.new(token: ENV['MONDAY_TOKEN'])

# Get account info
account = client.account.query
puts "Account: #{account.body.dig('data', 'users', 0, 'account', 'name')}"

# Get all boards
boards = client.board.query(args: {limit: 10})
board_id = boards.body.dig('data', 'boards', 0, 'id')

# Create a new item
new_item = client.item.create(
  args: {
    board_id: board_id,
    item_name: "New Task",
    column_values: {
      status: {label: "Working on it"},
      date: {date: "2024-12-31"}
    }
  }
)

item_id = new_item.body.dig('data', 'create_item', 'id')

# Update a column value
client.column.change_value(
  board_id: board_id,
  item_id: item_id,
  column_id: "status",
  value: {label: "Done"}
)

# Create an update
client.update.create(
  item_id: item_id,
  args: {body: "Task completed successfully!"}
)

# Archive the item
client.item.archive(item_id: item_id)

Conclusion

The migration from v0.x to v1.x requires updating how you access resources and method names, but the benefits far outweigh the effort. The new architecture provides:

Better code organization
More consistent API design
Easier maintenance and testing
Foundation for future features
Improved developer experience

Take your time with the migration, test thoroughly, and don't hesitate to reach out for help if you encounter issues. Welcome to monday_ruby v1.x!

Migration Guide: Upgrading to v1.0.0 ​

Overview of Changes ​

What Changed ​

Why These Changes Were Made ​

Breaking Changes ​

1. Resource Access Pattern ​

Before (v0.x) ​

After (v1.x) ​

2. Method Name Changes ​

Account Resource ​

Board Resource ​

Item Resource ​

Group Resource ​

Column Resource ​

Workspace Resource ​

Update Resource ​

Subitem Resource ​

Board View Resource ​

Activity Log Resource ​

Folder Resource ​

Migration Steps ​

Step 1: Update Your Gemfile ​

Step 2: Update Resource Access Patterns ​

Step 3: Update Method Names ​

Step 4: Test Thoroughly ​

Common Migration Scenarios ​

Scenario 1: Fetching and Creating Boards ​

Scenario 2: Working with Items ​

Scenario 3: Column Value Updates ​

Scenario 4: Workspace Management ​

What Stayed the Same ​

1. Configuration ​

2. Response Objects ​

3. Error Handling ​

4. Method Arguments ​

Common Migration Pitfalls ​

Pitfall 1: Forgetting the Resource Object ​

Pitfall 2: Using Old Method Names ​

Pitfall 3: Inconsistent Resource Names ​

Pitfall 4: Assuming Response Format Changed ​

New Features in v1.x ​

v1.0.0 Features ​

Enum Support ​

Better Code Organization ​

v1.1.0 Features ​

Cursor-Based Pagination ​

Configurable Timeouts ​

Deprecation Warning System ​

Benefits of Upgrading ​

1. Future-Proof Code ​

2. Better Developer Experience ​

3. Improved Maintainability ​

4. Ruby Best Practices ​

Timeline and Support ​

Version Support Policy ​

Migration Timeframe ​

Deprecation Timeline ​

Getting Help ​

Resources ​

Support Channels ​

Common Questions ​

Automated Migration Tools ​

Using Regex Find and Replace ​

Example: Complete Before and After ​

Before (v0.x) ​

After (v1.x) ​

Conclusion ​

Migration Guide: Upgrading to v1.0.0

Overview of Changes

What Changed

Why These Changes Were Made

Breaking Changes

1. Resource Access Pattern

Before (v0.x)

After (v1.x)

2. Method Name Changes

Account Resource

Board Resource

Item Resource

Group Resource

Column Resource

Workspace Resource

Update Resource

Subitem Resource

Board View Resource

Activity Log Resource

Folder Resource

Migration Steps

Step 1: Update Your Gemfile

Step 2: Update Resource Access Patterns

Step 3: Update Method Names

Step 4: Test Thoroughly

Common Migration Scenarios

Scenario 1: Fetching and Creating Boards

Scenario 2: Working with Items

Scenario 3: Column Value Updates

Scenario 4: Workspace Management

What Stayed the Same

1. Configuration

2. Response Objects

3. Error Handling

4. Method Arguments

Common Migration Pitfalls

Pitfall 1: Forgetting the Resource Object

Pitfall 2: Using Old Method Names

Pitfall 3: Inconsistent Resource Names

Pitfall 4: Assuming Response Format Changed

New Features in v1.x

v1.0.0 Features

Enum Support

Better Code Organization

v1.1.0 Features

Cursor-Based Pagination

Configurable Timeouts

Deprecation Warning System

Benefits of Upgrading

1. Future-Proof Code

2. Better Developer Experience

3. Improved Maintainability

4. Ruby Best Practices

Timeline and Support

Version Support Policy

Migration Timeframe

Deprecation Timeline

Getting Help

Resources

Support Channels

Common Questions

Automated Migration Tools

Using Regex Find and Replace

Example: Complete Before and After

Before (v0.x)

After (v1.x)

Conclusion