From 68e75c51cbac4c0246ef51c295723c5b0434a156 Mon Sep 17 00:00:00 2001 From: jchen293 Date: Wed, 30 Nov 2022 12:03:01 -0500 Subject: [PATCH] Add content to upgrade guide for v6 major bump (#208) --- UPGRADE_GUIDE.md | 153 +++++++++++++++++- .../{General => API}/ExternalApiError.java | 2 +- .../service/ReferralCustomerService.java | 2 +- src/test/java/com/easypost/ReferralTest.java | 2 +- 4 files changed, 151 insertions(+), 8 deletions(-) rename src/main/java/com/easypost/exception/{General => API}/ExternalApiError.java (88%) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index 370b617ac..d3b70bfba 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -2,22 +2,165 @@ Use the following guide to assist in the upgrade process of the `easypost-java` library between major versions. -* [Upgrading from 4.x to 5.0](#upgrading-from-4x-to-50) +- [Upgrading from 5.x to 6.0](#upgrading-from-5x-to-60) +- [Upgrading from 4.x to 5.0](#upgrading-from-4x-to-50) + +## Upgrading from 5.x to 6.0 + +### 6.0 High Impact Changes + +- [Client Instance](#60-client-instance) +- [Error Types](#60-error-types) +- [Empty Response Function Return Types](#60-empty-response-function-return-types) +- [Services and Resources](#60-services-and-resources) + +### 6.0 Medium Impact Changes + +- [Removal of Setters](#60-removal-of-setters) +- [Rename Some Getters](#60-rename-some-getters) + +### 6.0 Low Impact Changes + +- [Type Changes](#60-type-changes) + +## 6.0 Client Instance + +*Likelihood of Impact: **High*** + +The library is now designed around the idea of a `EasyPostClient`. Users will initialize an `EasyPostClient` instance with their API key and then use that instance to make API calls. + +This change allows for multiple clients to be instantiated with different API keys which allows this library to be safely used in a multi-threaded environment. + +```java +// Old +EasyPost.apiKey = System.getenv("EASYPOST_API_KEY"); // global API key + +// New +EasyPostClient client1 = new EasyPostClient("EASYPOST_API_KEY_1"); // per-client API key +EasyPostClient client2 = new EasyPostClient("EASYPOST_API_KEY_2"); // per-client API key +``` + +All functions are now accessed via the `EasyPostClient` instance. For example, to create a shipment: + +```java +// Old +EasyPost.apiKey = System.getenv("EASYPOST_API_KEY"); +Shipment shipment = Shipment.create(shipmentMap); + +// New +EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY_1"); +Shipment shipment = client.shipment.create(shipmentMap); +``` + +## 6.0 Error Types + +*Likelihood of Impact: **High*** + +Error handling has been overhauled and a number of specific exception types have been introduced. + +All exceptions inherit from `EasyPost.Exception.EasyPostException` (which extends `Java Exception` class). Users can catch this exception type to handle all errors thrown by the library. + +Subclasses of `EasyPostException` are grouped into two categories: + +- `EasyPost.Exception.API` for errors returned by the API. Subclasses of this exception type are: + - `ExternalApiError` - thrown when an issue occurs with an external API (e.g. Stripe) + - `ForbiddenError` - thrown when you don't have permission to access this API resource + - `GatewayTimeoutError` - thrown when the API gateway times out (504 status code) + - `InternalServerError` - thrown when an internal server error occurs (500 status code) + - `InvalidRequestError` - thrown when the API received an invalid request (422 status code) + - `MethodNotAllowedError` - thrown when the API receives a request with an invalid HTTP method ( + 405 status code) + - `NotFoundError` - thrown when the API receives a request for a resource that does not exist ( + 404 status code) + - `PaymentError` - thrown when a payment error occurs (402 status code) + - `ProxyError` - thrown when the library is unable to connect to the API via a proxy + - `RateLimitError` - thrown when the API rate limit is exceeded (429 status code) + - `RedirectError` - thrown when the http status is between 300 and 308. + - `ServiceUnavailableError` - thrown when the API is unavailable (503 status code) + - `TimeoutError` - thrown when the API request times out (408 status code) + - `UnauthorizedError` - thrown when the API receives an unauthorized request (401 or 403 status + code) + - `UnknownApiError` - thrown when an unknown API error occurs (unexpected 4xx status code) +- `EasyPost.Exception.General` for Generic error returned by the client library. Subclasses of this exception type are: + - `FilteringError` - thrown when an error occurs during filtering (e.g. calculating lowest rate) + - `InvalidObjectError` - thrown when an invalid object is being used + - `InvalidParameterError` - thrown when an invalid parameter is being used + - `MissingPropertyError` - thrown when a required property is missing (e.g. `Id` for most objects) + - `SignatureVerificationError` - thrown when the signature for a webhook is invalid + +Any exception thrown by the EasyPost library will be one of the above types. + +Any `EasyPost.Exception.API` exception will have the following properties: + +- `String Code` - the HTTP status code returned by the API call (e.g. 404) +- `String Message` - the error message returned by the API (e.g. "PARAMETER.INVALID") +- `List Errors` - a list of errors returned by the API (e.g. "Invalid parameter: to_address") + +Users can better anticipate exception information through utilities in the `EasyPost.Exception.Constants` file. + +## 6.0 Empty Response Function Return Types + +*Likelihood of Impact: **High*** + +The following functions return an empty body from the API have been changed to return void. + +- `fundWallet()` and `deletePaymentMethod()` in Billing class +- `createList()` in Tracker class +- `updateEmail()` in ReferralCustomer class + +## 6.0 Services and Resources + +*Likelihood of Impact: **High*** + +Static and instance-based methods have been divided into separate services and resources, methods that have API interactions are in services now. + +For example: + +- The static method `Shipment.buy()` is now accessible in the Shipment service via `client.shipment.buy("shp_...")`. +- The instance method `myShipment.lowestRate()` is still accessible only via a Shipment instance because there is no API interaction. +- The instance method of `refresh()` has been removed because you can no longer use an object to make a HTTP request. + +Instances of an object cannot be initialized directly. Instead, use the service to create the instance via a `create`, `retrieve`, or `all` API call. + +## 6.0 Removal of Setters + +*Likelihood of Impact: **Medium*** + +Objects no longer have setters. The use case of the setter is extremely low, but if you need to use the setter for a specific reason, try to use `reflection` in Java. + +## 6.0 Rename Some Getters + +*Likelihood of Impact: **Medium*** + +The following getters have been renamed: + +- Pickup class: `getPickoutRates()` -> `getPickupRates()` +- PaymentMethod class: `getPrimaryPaymentMethodObject()` -> `getPrimaryPaymentMethod()` +- PaymentMethod class: `getSecondaryPaymentMethodObject()` -> `getSecondaryPaymentMethod()` + +## 6.0 Type Changes + +*Likelihood of Impact: **Low*** + +The following properties have changed types: + +- `result` of Event from `EasyPostResource` to `Map` +- `amount` of Insurance from `Float` to `String` ## Upgrading from 4.x to 5.0 ### 5.0 High Impact Changes -* [Updating Dependencies](#50-updating-dependencies) -* [JSON Encoded Bodies](#50-json-encoded-bodies) +- [Updating Dependencies](#50-updating-dependencies) +- [JSON Encoded Bodies](#50-json-encoded-bodies) ### 5.0 Medium Impact Changes -* [Default Timeouts for HTTP Requests](#50-default-timeouts-for-http-requests) +- [Default Timeouts for HTTP Requests](#50-default-timeouts-for-http-requests) ### 5.0 Low Impact Changes -* [Removal of Item and Container Objects](#50-removal-of-item-and-container-objects) +- [Removal of Item and Container Objects](#50-removal-of-item-and-container-objects) ## 5.0 Updating Dependencies diff --git a/src/main/java/com/easypost/exception/General/ExternalApiError.java b/src/main/java/com/easypost/exception/API/ExternalApiError.java similarity index 88% rename from src/main/java/com/easypost/exception/General/ExternalApiError.java rename to src/main/java/com/easypost/exception/API/ExternalApiError.java index 14d32fe6f..d08db164d 100644 --- a/src/main/java/com/easypost/exception/General/ExternalApiError.java +++ b/src/main/java/com/easypost/exception/API/ExternalApiError.java @@ -1,4 +1,4 @@ -package com.easypost.exception.General; +package com.easypost.exception.API; import com.easypost.exception.EasyPostException; diff --git a/src/main/java/com/easypost/service/ReferralCustomerService.java b/src/main/java/com/easypost/service/ReferralCustomerService.java index 83c7bf42a..8a96ecb6a 100644 --- a/src/main/java/com/easypost/service/ReferralCustomerService.java +++ b/src/main/java/com/easypost/service/ReferralCustomerService.java @@ -2,7 +2,7 @@ import com.easypost.exception.Constants; import com.easypost.exception.EasyPostException; -import com.easypost.exception.General.ExternalApiError; +import com.easypost.exception.API.ExternalApiError; import com.easypost.http.Constant; import com.easypost.http.Requestor; import com.easypost.http.Requestor.RequestMethod; diff --git a/src/test/java/com/easypost/ReferralTest.java b/src/test/java/com/easypost/ReferralTest.java index 1802cdc4f..d254752c3 100644 --- a/src/test/java/com/easypost/ReferralTest.java +++ b/src/test/java/com/easypost/ReferralTest.java @@ -1,7 +1,7 @@ package com.easypost; import com.easypost.exception.EasyPostException; -import com.easypost.exception.General.ExternalApiError; +import com.easypost.exception.API.ExternalApiError; import com.easypost.model.PaymentMethod; import com.easypost.model.PaymentMethodObject; import com.easypost.model.ReferralCustomer;