Add content to upgrade guide for v6 major bump (#208)

Author: jchen293

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<Error> 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<String, object>`
+- `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
 

src/main/java/com/easypost/exception/General/ExternalApiError.java renamed to 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;
 

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;

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;