Ruby Migration Guide
Migrating the Ruby SDK from hellosign-ruby-sdk to dropbox-sign
Welcome! Dropbox Sign's new Ruby SDK is generated from our officially maintained OpenAPI spec. In this release, we've made important updates that introduce new functionality and create feature parity between the Dropbox Sign API and the Ruby SDK. However, some of these changes are considered "breaking" in the sense that they'll require you to update your existing code in order to continue using the SDK.
In this migration guide, we'll cover core concepts in the new SDK, highlight differences from legacy versions, and provide example code showing how past implementations map to the new version's syntax. We'll link out to supporting documents that offer more context behind the breaking changes and why we made them. We apologize for any inconvenience these changes may cause, but are confident the new features will add value to your integration.
Remember that we are here to help if you have any questions or need assistance along the way. Thank you for using Dropbox Sign's Ruby SDK. We hope you enjoy the improvements!
Architecture and Tooling
As mentioned above, the new Ruby SDK (dropbox-sign) is generated from our OpenAPI Spec. Some of the architectural changes impact the tools and locations you use to interact with the SDK.
SDK Resources
- Download -- using this new rubygems repo. New Ruby SDK versions will now be published here.
- Development -- active development against the Ruby SDK happens here: hellosign-openapi/sdks/ruby.
- SDK GitHub Repo -- dropbox-sign-ruby is updated based on changes to hellosign-openapi/sdks/ruby, but no active development work happens there.
- Reference Docs -- the automatically generated Reference Docs are a great way to explore the SDK.
- Examples -- our full suite of ready to use examples will help you get started quickly.
- Engagement -- use the OpenAPI repo to submit Issues or Pull Requests for the Ruby SDK.
Core Concepts and Patterns
This section contains the core concepts and patterns of the new SDK and highlights differences from the legacy SDK.
Installation
First time installation
Install the dropbox-sign gem:
Add the following to your Gemfile:
Updating gem version
Modify the version on your Gemfile to point to the New Ruby SDK package specified on Ruby gems. Or, if using the Gem locally, point to the version specified on our Github repo:
Run
bundle install
Importing the SDK
Authentication
The api_key parameter has been renamed to username, and it’s no longer possible to set the client_id on the configure block . The client_id must be set in each API call.
Endpoints Grouped into Classes
The New Ruby SDK no longer uses the Client class. New classes have been introduced to execute specific endpoints and you will now need to instantiate a model specific client to access the methods needed to make your API calls.
Using Models to Pass Parameters
Models are used to define the structure and value of the parameters being passed. The fully assembled model is passed to the API endpoint method.
New SDK Using Models to Pass Parameters
Path and Query Parameters
In the legacy SDK you would pass Path and Query parameters alongside any POST data to the API endpoint:
Legacy SDK - Path and Query Parameters
The new SDK now requires POST data be an object when calling any API endpoint. Path and Query parameters must be passed individually to these methods.
New SDK - Path and Query Parameters
Error Handling and Warnings
The New SDK handles errors and warnings differently.
Error Handling
Errors are an instance of Dropbox::Sign::ApiError with its body method returning an instance of Dropbox::Sign::ErrorResponse class and should be handled using begin/rescue blocks.
New SDK - Error Handling
Warnings
Warnings are a list of Dropbox::Sign::WarningResponse.
New SDK - Warnings
Instantiating Objects From Data
There are three ways to instantiate an object.
- You can instantiate a class directly and pass a hash of data
- You can use setter methods
- You can use the
init()static method
Note
init() creates a full object using all the data you pass, including nested data to instantiate nested objects. Any parameters that you do not pass data for will be set to their default value (including null).
Event Callback Helper
A callback helper class is included in the New SDK repo to assist in verifying callbacks. The helper simplifies:
- Checking event authenticity with built in event hash check
- Displaying event types (account callback vs. app callback)
- Displaying event messages
The EventCallbackHelper and EventCallbackRequest classes facilitate parsing of event data and assist in validating that a callback originated from Dropbox Sign.
We will send event callback payloads to you as a multipart/form-data request with a single json formfield that contains your event callback as a JSON string.
Example Event Callback Request From US to YOU
Example JSON Payload
How to use the EventCallbackHelper
Differences from Legacy SDK
This section highlights larger changes to be aware of when migrating to the new SDK.
Form Fields per Document
The Form Fields per Document parameter has changed from a two dimensional array, to a one dimensional array—allowing you to designate which file you to add the field to using document_index. You can learn more about this change here: Form Fields per Document.
Instantiating the Correct Field Class
There are several different types of form fields you can define, identified by the value of the type field and a few ways to instantiate the correct object when making an API request.
The different classes for each type are:
You can use ::init() on the base request class
You can use ::init() on the field class
You can instantiate the class directly
Form Fields per Document Examples using the new SDK:
“role” Value in signers Object
In the Legacy SDK when making a Signature Request using a Template the signers property was an object with the role name as the key. In the new SDK the role value has been moved into the signer object itself.
For example for the /signature_request/send_with_template endpoint the signers property could be represented as:
Using the new SDK you would now send this data as follows:
“role” Value in ccs Property
In the Legacy SDK when making a Signature Request using a Template the ccs property was an object with the role name as the key. In the new SDK the role value has been moved into the cc object itself, alongside a new email_address property.
For example for the /signature_request/send_with_template endpoint the ccs property could be represented as:
Using the new SDK you would now send this data as follows:
“name” Value in custom_fields Property
In the Legacy SDK when making a Signature Request with the custom_fields property it was an object with the name as the key. In the new SDK the name value has been moved into the custom_field object itself.
For example for the /signature_request/send_with_template endpoint the custom_fields property could be represented as:
Using the new SDK you would now send this data as follows:
template_id to template_ids
The template_id parameter has been removed. You must now use template_ids.
file to files
The file parameter has been renamed to files. Usage remains the same.
Use .files([...]);
file_url to file_urls
The file_url parameter has been renamed to file_urls. Usage remains the same.
Use .file_urls([...]);
Interacting with Files
The new SDK version introduces some new patterns around uploading and downloading files. You can read about them more in depth here: Interacting with Files.
Uploading Files
The file upload process changed with the newly-adopted OpenAPI-specification — it is no longer possible to pass file paths into file upload methods. You can learn more about this update here: New Patterns: Interacting with Files.
Legacy SDK
- Supports passing filepath as a string
New Ruby SDK
- Files needs to be instance of
File - Construct instance of
Fileusing eitherFile.openorFile.new
Downloading Files
The file retrieval process changed with the newly-adopted OpenAPI-specification — one endpoint was branched off into three separate endpoints. You can learn more about this update here: New Patterns: Interacting with Files.
Legacy SDK
- Returns different file formats depending on parameters used from a single endpoint.
New SDK
- Original endpoint broken into 3 separate endpoints to return different file formats.
Downloading Templates
Endpoint Mapping
This section shows you how endpoints in the legacy SDK map to the new SDK. It doesn’t cover all endpoints, but gives you an idea of mapping implementations between the two SDKs. Please reach out if you think we’re missing an important example.
- Non-Embedded Signature Request
- Embedded Signature Request
- Send Signature Request with Template
- Get Signature Request
- List Signature Request
- Download Files
- Get Account
Non-Embedded Signature Request
Embedded Signature Request
Send Signature Request with Template
Get Signature Request
List Signature Request
Download Files
Get Account
Supporting Legacy SDKs
Following the official release of the new SDK version, we'll be preparing to deprecate all legacy versions of the Ruby SDK for one year after launch. That means, once fully launched, we'll only support critical vulnerabilities and bug fixes for legacy SDK versions 3.7.7 for 12 months. After that, legacy versions are considered officially deprecated and are no longer supported. You can find more information in our SDK Versioning Policy.
We encourage you to start migrating (or planning to migrate) to the new SDK as soon as possible. Please don't hesitate to reach out if you have questions or need assistance.
Feedback and Assistance
We know that dealing with "breaking" changes is inconvenient for those of you currently using the legacy SDK, but believe the new SDK offers a better experience while providing access to more features. If you need help or get stuck, please reach out to API support: Submit a Ticket
We warmly welcome your feedback, feature requests, and bug reports in our OpenAPI repo. All of the engineering work on the Ruby SDK happens in the Ruby folder of the repo.