From e2638671f6e7729bd7a777964513a5a250e1c5eb Mon Sep 17 00:00:00 2001 From: jchen293 Date: Tue, 29 Nov 2022 17:07:50 -0500 Subject: [PATCH 1/4] Add content to upgrade guide for v6 major bump --- UPGRADE_GUIDE.md | 118 +++++++++++++++++- .../{General => API}/ExternalApiError.java | 2 +- .../service/ReferralCustomerService.java | 2 +- 3 files changed, 115 insertions(+), 7 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..c82859fa8 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -2,22 +2,130 @@ 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) +- [Uniform empty response](#60-uniform-empty-response) + +### 6.0 Low Impact Changes + +- [Services and Resources](#60-services-and-resources) + +## 6.0 Client Instance + +*Likelihood of Impact: **High*** + +The library is now designed around the idea of a `EasyPostClient`. Users will initialize a `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 and for the library to be 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 `System.Exception`). 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: + - `EasyPost.Exception.ExternalApiError` - thrown when an issue occurs with an external API (e.g. Stripe) + - `EasyPost.Exception.ForbiddenError` - thrown when you don't have permission to access this API resource + - `EasyPost.Exception.GatewayTimeoutError` - thrown when the API gateway times out (504 status code) + - `EasyPost.Exception.InternalServerError` - thrown when an internal server error occurs (500 status code) + - `EasyPost.Exception.InvalidRequestError` - thrown when the API received an invalid request (422 status code) + - `EasyPost.Exception.MethodNotAllowedError` - thrown when the API receives a request with an invalid HTTP method ( + 405 status code) + - `EasyPost.Exception.NotFoundError` - thrown when the API receives a request for a resource that does not exist ( + 404 status code) + - `EasyPost.Exception.PaymentError` - thrown when a payment error occurs (402 status code) + - `EasyPost.Exception.ProxyError` - thrown when the library is unable to connect to the API via a proxy + - `EasyPost.Exception.RateLimitError` - thrown when the API rate limit is exceeded (429 status code) + - `EasyPost.Exception.RedirectError` - thrown when the http status is between 300 and 308. + - `EasyPost.Exception.ServiceUnavailableError` - thrown when the API is unavailable (503 status code) + - `EasyPost.Exception.TimeoutError` - thrown when the API request times out (408 status code) + - `EasyPost.Exception.UnauthorizedError` - thrown when the API receives an unauthorized request (401 or 403 status + code) + - `EasyPost.Exception.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: + - `EasyPost.Exceptions.FilteringError` - thrown when an error occurs during filtering (e.g. calculating lowest rate) + - `EasyPost.Exceptions.InvalidObjectError` - thrown when an invalid object is being used + - `EasyPost.Exceptions.InvalidParameterError` - thrown when an invalid parameter is being used + - `EasyPost.Exceptions.MissingPropertyError` - thrown when a required property is missing (e.g. `Id` for most objects) + - `EasyPost.Exceptions.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 Uniform empty response + +*Likelihood of Impact: **High*** + +Below functions return empty bodies or boolean have been changed to void. + +- `fundWallet()` and `deletePaymentMethod()` in Billing class +- `createList()` in Tracker class +- `updateEmail()` in ReferralCustomer class + +## 6.0 Services and Resources + +*Likelihood of Impact: **Low*** + +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.Create` is now accessible in the Shipment service via `client.Shipment.Create`. The instance method `myShipment.lowestRate` is still accessible only via a Shipment instance. + +Instances of an object cannot be initialized directly. Instead, use the service to create the instance via a `Create`, `Retrieve`, or `All` API call. ## 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; From 5786cd2c0c9797e1cd2e46f11f60abc097d9334f Mon Sep 17 00:00:00 2001 From: jchen293 Date: Tue, 29 Nov 2022 18:29:42 -0500 Subject: [PATCH 2/4] address feedback --- UPGRADE_GUIDE.md | 97 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 66 insertions(+), 31 deletions(-) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index c82859fa8..a7322e3da 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -11,21 +11,25 @@ Use the following guide to assist in the upgrade process of the `easypost-java` - [Client Instance](#60-client-instance) - [Error Types](#60-error-types) -- [Uniform empty response](#60-uniform-empty-response) +- [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 -- [Services and Resources](#60-services-and-resources) +- [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 a `EasyPostClient` instance with their API key -and then use that instance to make API calls. +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 and for the library to be used in a -multi-threaded environment. +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 @@ -54,35 +58,35 @@ Shipment shipment = client.shipment.create(shipmentMap); Error handling has been overhauled and a number of specific exception types have been introduced. -All exceptions inherit from `EasyPost.Exception.EasyPostException` (which extends `System.Exception`). Users can catch this exception type to handle all errors thrown by the library. +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: - - `EasyPost.Exception.ExternalApiError` - thrown when an issue occurs with an external API (e.g. Stripe) - - `EasyPost.Exception.ForbiddenError` - thrown when you don't have permission to access this API resource - - `EasyPost.Exception.GatewayTimeoutError` - thrown when the API gateway times out (504 status code) - - `EasyPost.Exception.InternalServerError` - thrown when an internal server error occurs (500 status code) - - `EasyPost.Exception.InvalidRequestError` - thrown when the API received an invalid request (422 status code) - - `EasyPost.Exception.MethodNotAllowedError` - thrown when the API receives a request with an invalid HTTP method ( + - `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) - - `EasyPost.Exception.NotFoundError` - thrown when the API receives a request for a resource that does not exist ( + - `NotFoundError` - thrown when the API receives a request for a resource that does not exist ( 404 status code) - - `EasyPost.Exception.PaymentError` - thrown when a payment error occurs (402 status code) - - `EasyPost.Exception.ProxyError` - thrown when the library is unable to connect to the API via a proxy - - `EasyPost.Exception.RateLimitError` - thrown when the API rate limit is exceeded (429 status code) - - `EasyPost.Exception.RedirectError` - thrown when the http status is between 300 and 308. - - `EasyPost.Exception.ServiceUnavailableError` - thrown when the API is unavailable (503 status code) - - `EasyPost.Exception.TimeoutError` - thrown when the API request times out (408 status code) - - `EasyPost.Exception.UnauthorizedError` - thrown when the API receives an unauthorized request (401 or 403 status + - `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) - - `EasyPost.Exception.UnknownApiError` - thrown when an unknown API error occurs (unexpected 4xx 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: - - `EasyPost.Exceptions.FilteringError` - thrown when an error occurs during filtering (e.g. calculating lowest rate) - - `EasyPost.Exceptions.InvalidObjectError` - thrown when an invalid object is being used - - `EasyPost.Exceptions.InvalidParameterError` - thrown when an invalid parameter is being used - - `EasyPost.Exceptions.MissingPropertyError` - thrown when a required property is missing (e.g. `Id` for most objects) - - `EasyPost.Exceptions.SignatureVerificationError` - thrown when the signature for a webhook is invalid + - `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. @@ -94,11 +98,11 @@ Any `EasyPost.Exception.API` exception will have the following properties: Users can better anticipate exception information through utilities in the `EasyPost.Exception.Constants` file. -## 6.0 Uniform empty response +## 6.0 Empty Response Function Return Types *Likelihood of Impact: **High*** -Below functions return empty bodies or boolean have been changed to void. +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 @@ -106,11 +110,42 @@ Below functions return empty bodies or boolean have been changed to void. ## 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 becasue you can no longer use 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*** + +Each object no longer has 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*** + +Below getters have been renamed: + +- Pickup class: `getPickoutRates()` -> `getPickupRates()` +- PaymentMethod class: `getPrimaryPaymentMethodObject()` -> `getPrimaryPaymentMethod()` +- PaymentMethod class: `getSecondaryPaymentMethodObject()` -> `getSecondaryPaymentMethod()` + +## 6.0 Type Changes + *Likelihood of Impact: **Low*** -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.Create` is now accessible in the Shipment service via `client.Shipment.Create`. The instance method `myShipment.lowestRate` is still accessible only via a Shipment instance. +Change the below type of objects: -Instances of an object cannot be initialized directly. Instead, use the service to create the instance via a `Create`, `Retrieve`, or `All` API call. +- `result` of Event from `EasyPostResource` to `Map` +- `amount` of Insurance from `Float` to `String` ## Upgrading from 4.x to 5.0 From 0cdc3b188da26702202433aca86b4297f72b5a0c Mon Sep 17 00:00:00 2001 From: jchen293 Date: Wed, 30 Nov 2022 11:42:45 -0500 Subject: [PATCH 3/4] fix grammar/spelling --- UPGRADE_GUIDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index a7322e3da..d3b70bfba 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -116,9 +116,9 @@ Static and instance-based methods have been divided into separate services and r For example: -- The static method `Shipment.buy()` is now accessible in the Shipment service via `client.shipment.buy("shp_...")`. +- 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 becasue you can no longer use object to make a HTTP request. +- 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. @@ -126,13 +126,13 @@ Instances of an object cannot be initialized directly. Instead, use the service *Likelihood of Impact: **Medium*** -Each object no longer has 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. +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*** -Below getters have been renamed: +The following getters have been renamed: - Pickup class: `getPickoutRates()` -> `getPickupRates()` - PaymentMethod class: `getPrimaryPaymentMethodObject()` -> `getPrimaryPaymentMethod()` @@ -142,7 +142,7 @@ Below getters have been renamed: *Likelihood of Impact: **Low*** -Change the below type of objects: +The following properties have changed types: - `result` of Event from `EasyPostResource` to `Map` - `amount` of Insurance from `Float` to `String` From c3efe02548714caaee555f8843f3afd03176bf56 Mon Sep 17 00:00:00 2001 From: jchen293 Date: Wed, 30 Nov 2022 11:52:29 -0500 Subject: [PATCH 4/4] fix import and CI build --- src/test/java/com/easypost/ReferralTest.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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;