Use the following guide to assist in the upgrade process of the easypost-go
library between major versions.
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 CarbonOffset
field from createShipmentRequest
, buyShipmentRequest
, and buyShipmentRequest
structs have been removed as a result. This is a high-impact change for those using EndShippers
as the function interfaces have changed. You will need to inspect the callsites to create and buy shipments to ensure that the EndShipper parameter is being passed in the correct place now that the CarbonOffset
field has been removed from the structs.
The CreateAndBuy
Batch endpoint has been deprecated and removed from the library. The correct procedure is to first create a batch and then purchase it with two separate API calls.
NOTICE: v3 is deprecated.
- Importing the Library
- Updating Dependencies
- New
DateTime
Type - Deprecated Methods and Structs Removed
- Error Types
Likelihood of Impact: High
With the transition to v3
, this library must now be imported as follows:
import (
"github.com/EasyPost/easypost-go/v3"
)
Likelihood of Impact: High
Go 1.16 Required
easypost-go now requires Go 1.16 or greater.
Dependencies
Some dependencies had minor version bumps.
Likelihood of Impact: High
All uses of time.Time
in the library (including in parameter and API response structs) have been replaced with a new DateTime
type.
This type is a wrapper around time.Time
that handles unexpected datetime formats returned by the API.
DateTime
should be a drop-in replacement for time.Time
in most cases:
// Before
var t time.Time
t := time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC)
// After
var t easypost.DateTime
t := easypost.DateTime(time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC))
// or
t := easypost.DateTimeFromTime(time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC))
// or
t := easypost.NewDateTime(2021, 1, 1, 0, 0, 0, 0, time.UTC)
DateTime
objects can be converted to time.Time
objects using the AsTime()
method:
var t easypost.DateTime
t := easypost.NewDateTime(2021, 1, 1, 0, 0, 0, 0, time.UTC)
t.AsTime() // time.Time
Likelihood of Impact: High
All methods and structs marked as deprecated in v2
have been removed.
The following is a list of items that have been removed, along with their suggested replacements:
Deprecated | Replacement |
---|---|
ListReportOptions struct |
ListOptions struct |
BetaCarrierMetadata methods and structs |
CarrierMetadata methods and structs |
LowestRate shipment method |
LowestShipmentRate method |
CreateWebhook method |
CreateWebhookWithDetails method |
EnableWebhook method |
UpdateWebhook method |
Likelihood of Impact: High
Error handling has been overhauled and a number of specific exception types have been introduced.
All exceptions inherit from easypost.LibraryError
.
Subclasses of easypost.LibraryError
are grouped into two categories:
easypost.APIError
for errors returned by the API. Users will need to anticipate one or multiple of the following errors that inherit this class:easypost.BadRequestError
- thrown when the API returns a 400 status codeeasypost.UnauthorizedError
- thrown when the API returns a 401 status codeeasypost.PaymentError
- thrown when the API returns a 402 status codeeasypost.ForbiddenError
- thrown when the API returns a 403 status codeeasypost.NotFoundError
- thrown when the API returns a 404 status codeeasypost.MethodNotAllowedError
- thrown when the API returns a 405 status codeeasypost.ProxyError
- thrown when the API returns a 407 status codeeasypost.TimeoutError
- thrown when the API returns a 408 status codeeasypost.InvalidRequestError
- thrown when the API returns a 422 status codeeasypost.RateLimitError
- thrown when the API returns a 429 status codeeasypost.InternalServerError
- thrown when the API returns a 500 status codeeasypost.GatewayTimeoutError
- thrown when the API returns a 502 or 504 status codeeasypost.ServiceUnavailableError
- thrown when the API returns a 503 status codeeasypost.RedirectError
- thrown when the API returns a 3xx status codeeasypost.RetryError
- thrown when the API returns a 1xx status codeeasypost.UnknownError
- thrown when the API returns an unexpected status codeeasypost.SSLError
- thrown when there is an SSL error
easypost.LocalError
for errors raised by local operations, such as validation, JSON de/serialization or list filtering.easypost.EndOfPaginationError
- thrown when the end of a paginated list is reachedeasypost.FilteringError
- thrown when there is an issue running a filtering operationeasypost.InvalidObjectError
- thrown when an object is invalideasypost.MissingPropertyError
- thrown when a required property is missingeasypost.MissingWebhookSignatureError
- thrown when a webhook signature is missingeasypost.MismatchWebhookSignatureError
- thrown when a webhook signature does not matcheasypost.ExternalApiError
- thrown when there is an error with an external API (e.g. Stripe)
Any error type can be pretty-printed as a string using the Error()
method:
_, err := client.CreateAddress(&easypost.Address{
Name: "Invalid Address",
})
fmt.Println(err.Error()) // "PARAMETER.REQUIRED Missing required parameter"
Any easypost.APIError
-derived error type will have the following properties:
Code
- An error code string referring to the specific error that occurred server-sideStatusCode
- The HTTP status code returned by the APIMessage
- A human-readable message describing the errorErrors
- A slice ofeasypost.Error
structs, representing specific details of server-side errors encountered
Any easypost.LocalError
-derived error type will have the following properties:
Message
- A human-readable message describing the error
Common strings and templates used to construct error messages are available as constants (e.g. easypost.NoRatesMatchingFilters
). These can be used to perform regex-based evaluation of error messages.
Note: An easypost.LibraryError
and its subclasses represent errors that occur within this library. This is different from easypost.Error
, which is a struct representing a server-side error returned by a failed API call.
Likelihood of Impact: Medium
The TrackingCodes
parameter for the ListTrackers
method has been renamed to TrackingCode
to match the API.
Instead of passing a slice of strings, you should now pass a single string:
// Before
trackers, err := client.ListTrackers(&easypost.ListTrackersOptions{
TrackingCodes: []string{"EZ1000000001", "EZ1000000002"},
})
// After
trackers, err := client.ListTrackers(&easypost.ListTrackersOptions{
TrackingCode: "EZ1000000001",
})
Likelihood of Impact: Medium
The AddShipmentsToBatch
and RemoveShipmentsFromBatch
methods now explicitly accept Shipment
structs instead of generic interface{}
types
These methods will no longer accept solely IDs; users will need to provide whole Shipment
structs
// Before
batch, err := client.AddShipmentsToBatch("batch_123", shipment1.ID, shipment2.ID)
// After
batch, err := client.AddShipmentsToBatch("batch_123", shipment1, shipment2)
Likelihood of Impact: High
With the transition to v2
, this library must now be imported as follows:
import (
"github.com/EasyPost/easypost-go/v2"
)
Likelihood of Impact: High
Go 1.15 Required
easypost-go now requires Go 1.15 or greater.
Dependencies
All dependencies had minor version bumps.
Likelihood of Impact: Medium
Default timeouts for all HTTP requests are now set to 60 seconds. If you require longer timeouts, you can set them by overriding the defaults:
client := &easypost.Client{
Timeout: 60000,
}
Likelihood of Impact: Medium
The HTTP method used for the GetShipmentRates
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 RerateShipment
method to regenerate rates. Due to the logic change, the GetShipmentRates
method has been removed since a Shipment inherently already has rates associated.