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.