Use the following guide to assist in the upgrade process of the easypost-ruby library between major versions.
Likelihood of Impact: High
EasyPost now offers Carbon Neutral shipments by default for free! Because of this, there is no longer a need to specify if you want to offset the carbon footprint of a shipment.
The with_carbon_offset parameter of the create, buy, and regenerate_rates shipment functions has been removed.
This is a high-impact change for those using EndShippers, as the signature for the create and buy shipment function has changed. You will need to inspect these callsites to ensure that the EndShipper parameter is being passed in the correct place.
Likelihood of Impact: Low
The create_and_buy batch endpoint has been deprecated, and the create_and_buy Batch service function has been removed.
The correct procedure is to first create a batch and then purchase it with two separate API calls.
NOTICE: v5 is deprecated.
Likelihood of Impact: High
This library is now thread-safe with the introduction of a new Client object. Instead of defining a global API key that all requests use, you now create an Client object and pass your API key to it with optional open and read timeout params. You then call your desired functions against a service which are called against a Client object:
# Old way
EasyPost.api_key = ENV['EASYPOST_API_KEY']
shipment = EasyPost::Shipment.retrieve('shp_...')
# New way
client = EasyPost::Client.new(api_key: ENV['EASYPOST_TEST_API_KEY'])
shipment = client.shipment.retrieve('shp_...')All instance methods are now static with the exception of lowest_rate as these make API calls and require the Client object(EasyPost objects do not contain an API key to make API calls with).
Previously used .save() instance methods are now static .update() functions where you specify first the ID of the object you are updating and second, the parameters that need updating.
Likelihood of Impact: High
Ruby 2.6 Required
easypost-ruby now requires Ruby 2.6 or greater.
Dependencies
All dependencies had minor version bumps.
Likelihood of Impact: High
There are ~2 dozen new error types that extend either ApiError or EasyPostError.
New ApiErrors (extends EasyPostError):
ApiErrorConnectionErrorExternalApiErrorForbiddenErrorGatewayTimeoutErrorInternalServerErrorInvalidRequestErrorMethodNotAllowedErrorNotFoundErrorPaymentErrorProxyErrorRateLimitErrorRedirectErrorRetryErrorServiceUnavailableErrorSSLErrorTimeoutErrorUnauthorizedErrorUnknownApiError
New EasyPostErrors (extends builtin Exception):
EasyPostErrorEndOfPaginationErrorFilteringErrorInvalidObjectErrorInvalidParameterErrorMissingParameterErrorSignatureVerificationError
ApiErrors will behave like the previous Error class did. They will include a message, http_status, and http_body. Additionally, a new code and errors keys are present and populate when available. This class extends the more generic EasyPostError which only contains a message, used for errors thrown directly from this library.
Likelihood of Impact: Medium
Occurances of referral are now referral_customer and Referral are now ReferralCustomer to match the documentation and API.
Occurances of smartrate are now smart_rate and Smartrate are now SmartRate to match the documentation and API.
Occurances of scanform are now scan_form and Scanform are now ScanForm to match the documentation and API.
Rename function get_smartrates to get_smart_rates
Rename function get_lowest_smartrate to get_lowest_smart_rate
Likelihood of Impact: Low
Previously, the beta namespace was found at easypost.beta.x where x is the name of your model. Now, the beta namespace is simply prepended to the name of your service: client.beta_x. for instance, you can call client.beta_referral_customer.add_payment_method().
Likelihood of Impact: Low
Empty API response functions for delete return true instead of empty object
NOTICE: v4 is deprecated.
- Removal of
PrintandPrintJobObjects - Removal of
stamp_and_barcode_by_referenceBatch Method - Removal of
Address.verifyParameters - Removal of the
http_statusProperty on EasyPost::Error
Likelihood of Impact: High
Ruby 2.5 Required
easypost-ruby now requires Ruby 2.5 or greater.
Dependencies
No production dependencies were altered. Development dependencies were all bumped and simplecov and rubocop were introduced.
Likelihood of Impact: Medium
The HTTP method used for the get_rates endpoint at the API level has changed from POST to GET and will only retrieve rates for a shipment instead of regenerating them. A new /rerate endpoint has been introduced to replace this functionality; In this library, you can now call the Shipment.regenerate_rates method to regenerate rates. Due to the logic change, the get_rates method has been removed since a Shipment inherently already has rates associated.
Likelihood of Impact: Low
The Print and PrintJob objects have been removed as they are no longer usable with the current version of the API.
Likelihood of Impact: Low
The stamp_and_barcode_by_reference Batch method has been removed as it is no longer usable with the current version of the API.
Likelihood of Impact: Low
The parameters for the Address.verify method were removed as they were unusable, the current version of the API does not allow you to verify an address by specifying a carrier.
Likelihood of Impact: Low
The deprecated http_status property has been removed in favor of the status property on the EasyPost::Error object.