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 nowknock.users.update()
Knock::Users.set_preferences()
is nowknock.recipients.preferences.set()
Knock::Users.get_channel_data()
is nowknock.recipients.channel_data.get()
Knock::Users.getSchedules()
is nowknock.users.listSchedules()
Knock::Workflows.createSchedules()
is nowknock.schedules.create()
Knock::Workflows.listSchedules()
is nowknock.schedules.list()
Knock::Workflows.updateSchedules()
is nowknock.schedules.update()
Knock::Workflows.deleteSchedules()
is nowknock.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#
Need help?#
If you run into any issues during your migration, reach out to our support team or open an issue on GitHub.