Developer tools
Migration guides
Ruby 1.0

Ruby SDK upgrade (v0.x to v1.0)

Learn how to upgrade to v1.0 of the Knock Ruby SDK.

Basic changes

#

Client initialization

#

Initialize a client instance with your API key:

What's new in v1.0

#

The v1.0 SDK brings strong typing with Sorbet, auto-pagination, and enhanced error handling to the Ruby ecosystem.

Strong typing with Sorbet

#

Improved type definitions for better IDE integration.

Auto-pagination

#

Iterate through paginated resources automatically:

Enhanced error handling

#

Handle errors more effectively with improved error classes:

Configurable timeouts and retries

#

Fine-tune request behavior by customizing timeouts and retry limits:

New resources

#

Work with additional resources like Audiences, Channels, and Integrations:

Request options

#

More control over individual requests:

Breaking changes

#

Client design

#

The new SDK uses an instance-based client rather than module functions. Create a client instance with knock = Knockapi::Client.new() and call methods via the client: knock.workflows.trigger() instead of Knock::Workflows.trigger().

Method naming and organization

#

The main module is now Knockapi instead of Knock.

Bulk operations are now organized in their own namespaces: knock.users.bulk.*, knock.objects.bulk.*, knock.schedules.bulk.*, etc.

Several method names have changed:

  • Knock::Users.identify() is now knock.users.update()
  • Knock::Users.set_preferences() is now knock.recipients.preferences.set()
  • Knock::Users.get_channel_data() is now knock.recipients.channel_data.get()
  • Knock::Users.getSchedules() is now knock.users.listSchedules()
  • Knock::Workflows.createSchedules() is now knock.schedules.create()
  • Knock::Workflows.listSchedules() is now knock.schedules.list()
  • Knock::Workflows.updateSchedules() is now knock.schedules.update()
  • Knock::Workflows.deleteSchedules() is now knock.schedules.delete()

Method parameters

#

Most methods now take the ID(s) as positional parameter(s), followed by named parameters. Resource IDs moved from named parameters to positional parameters (e.g., id: "user-1" is now "user-1"). data: parameters have been flattened in most methods.

Preference management

#

Preferences are now handled through the recipients.preferences module. The preference set ID must be explicitly provided (usually "default").

Response handling

#

The new SDK returns model instances rather than raw hashes. Pagination is handled via cursor-based pagination instead of page-based.

Common operations

#

Old SDK:

New SDK:

Old SDK:

New SDK:

Old SDK:

New SDK:

Need help?

#

If you run into any issues during your migration, reach out to our support team or open an issue on GitHub.