Skip to content

Commit 611d0b4

Browse files
jimmyjamesjimmyjames
authored
[SDK-3875] Added migration guide (#491)
1 parent 2d5eb72 commit 611d0b4

1 file changed

Lines changed: 154 additions & 0 deletions

File tree

‎MIGRATION_GUIDE.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Migration Guide
2+
3+
## Migrating from v1 to v2
4+
5+
The version 2 release includes several notable improvements, including:
6+
7+
* Requests can now be configured with additional parameters and headers, without needing to downcast to `CustomRequest`.
8+
* Responses are now wrapped in a new `com.auth0.net.Response` type, which provides information about the HTTP response such as headers and status code.
9+
* The `AuthAPI` and `ManagementAPI` clients can now share the same HTTP client.
10+
* The `AuthAPI` client no longer requires a client secret, enabling support for APIs and scenarios where a secret is not required.
11+
12+
Version 2 includes breaking changes. Please read this guide to learn how to update your application for v2.
13+
14+
### Configuring `auth0-java` v2
15+
16+
To create the API clients, use the new builders, and specify any HTTP-related configurations with the new `DefaultHttpClient`:
17+
18+
```java
19+
Auth0HttpClient http = DefaultHttpClient.newBuilder()
20+
.withConnectTimeout(10)
21+
.withReadTimeout(10)
22+
// additional configurations as needed
23+
.build();
24+
25+
AuthAPI auth = AuthAPI.newBuilder("{DOMAIN}", "{CLIENT-ID}", "{OPTIONAL-CLIENT-SECRET}")
26+
.withHttpClient(http)
27+
.build();
28+
29+
ManagementAPI mgmt = ManagementAPI.newBuilder("{DOMAIN}", "{API-TOKEN}")
30+
.withHttpClient(http)
31+
.build();
32+
```
33+
34+
### Response information
35+
36+
Version 2 returns HTTP response information such as status code and headers in a new `com.auth0.net.Response` type.
37+
Instead of simply returning the parsed JSON response body from requests, all API methods now return a `Response<T>`.
38+
If you have no need for the response information, replace any calls to `execute()` with `execute().getBody()` to get the returned response body as before:
39+
40+
```java
41+
// Get response info
42+
Response<User> userResponse = api.users().get("{USER-ID}", null);
43+
int code = userResponse.getStatusCode();
44+
Map<String, String> headers = userResponse.getHeaders();
45+
46+
// Just get the response body
47+
User user = api.users().get("{USER-ID}", null).execute().getBody();
48+
```
49+
50+
### Request configuration
51+
52+
Previously, only requests that returned a `CustomizableRequest` (or its implementation, `CustomRequest`) allowed for a request to be configured with additional parameters or headers.
53+
In v2, the `com.auth0.net.Request` interface defines the new methods:
54+
55+
- `Request<T> addHeader(String name, String value)`
56+
- `Request<T> addParameter(String name, Object value)`
57+
- `Request<T> setBody(Object body)`
58+
59+
This enables all requests to be configured, without the need to downcast to `CustomizableRequest` or `CustomRequest`.
60+
If you were down-casting to these types, you will need to remove the cast and instead configure the request directly:
61+
62+
```java
63+
Request<User> userRequest = api.users().get("{USER-ID}", null);
64+
userRequest.addHeader("some-header", "some-value");
65+
Response<User> userResponse = userRequest.execute();
66+
```
67+
68+
### Detailed changes
69+
70+
The following summarizes details of the changes in version 2, including types and methods removed, added, or deprecated.
71+
72+
#### Removed classes
73+
74+
- `AuthRequest` has been removed. Use `TokenRequest` instead.
75+
- `CustomizableRequest` and `CustomRequest` have been removed. The `Request` interface now supports request customization directly without the need to downcast.
76+
- `FormDataRequest` has been removed. Use `MultipartRequest` instead.
77+
- `CreateUserRequest` has been removed. Use `SignUpRequest` instead.
78+
79+
#### Moved classes
80+
81+
- `com.auth0.json.mgmt.Token` moved to `com.auth0.json.mgmt.blacklists.Token`
82+
- `com.auth0.json.mgmt.ClientGrant` moved to `com.auth0.json.mgmt.clientgrants.ClientGrant`
83+
- `com.auth0.json.mgmt.ClientGrantsPage` moved to `com.auth0.json.mgmt.clientgrants.ClientGrantsPage`
84+
- `com.auth0.json.mgmt.Connection` moved to `com.auth0.json.mgmt.connections.Connection`
85+
- `com.auth0.json.mgmt.ConnectionsPage` moved to `com.auth0.json.mgmt.connections.ConnectionsPage`
86+
- `com.auth0.json.mgmt.DeviceCredentials` moved to `com.auth0.json.mgmt.devicecredentials.DeviceCredentials`
87+
- `com.auth0.json.mgmt.EmailTemplate` moved to `com.auth0.json.mgmt.emailtemplates.EmailTemplate`
88+
- `com.auth0.json.mgmt.Grant` moved to `com.auth0.json.mgmt.grants.Grant`
89+
- `com.auth0.json.mgmt.GrantsPage` moved to `com.auth0.json.mgmt.grants.GrantsPage`
90+
- `com.auth0.json.mgmt.EmailVerificationIdentity` moved to `com.auth0.json.mgmt.tickets.EmailVerificationIdentity`
91+
- `com.auth0.json.mgmt.Key;` moved to `com.auth0.json.mgmt.keys.Key`
92+
- `com.auth0.json.mgmt.RolesPage` moved to `com.auth0.json.mgmt.roles.RolesPage`
93+
- `com.auth0.json.mgmt.ResourceServer` moved to `com.auth0.json.mgmt.resourceserver.ResourceServer`
94+
- `com.auth0.json.mgmt.ResourceServersPage` moved to `com.auth0.json.mgmt.resourceserver.ResourceServersPage`
95+
- `com.auth0.json.mgmt.Permission` moved to `com.auth0.json.mgmt.permissions.Permission`
96+
- `com.auth0.json.mgmt.PermissionsPage` moved to `com.auth0.json.mgmt.permissions.PermissionsPage`
97+
- `com.auth0.json.mgmt.Role` moved to `com.auth0.json.mgmt.roles.Role`
98+
- `com.auth0.json.mgmt.RolesPage` moved to `com.auth0.json.mgmt.roles.RolesPage`
99+
- `com.auth0.json.mgmt.RulesConfig` moved to `com.auth0.json.mgmt.rules.RulesConfig`
100+
- `com.auth0.json.mgmt.Rule` moved to `com.auth0.json.mgmt.rules.Rule`
101+
- `com.auth0.json.mgmt.RulesPage` moved to `com.auth0.json.mgmt.rules.RulesPage`
102+
- `com.auth0.json.mgmt.DailyStats` moved to `com.auth0.json.mgmt.stats.DailyStats`
103+
- `com.auth0.json.mgmt.Permission` moved to `com.auth0.json.mgmt.permissions.Permission`
104+
- `com.auth0.json.mgmt.PermissionsPage` moved to `com.auth0.json.mgmt.permissions.PermissionsPage`
105+
- `com.auth0.json.mgmt.RolesPage` moved to `com.auth0.json.mgmt.roles.RolesPage`
106+
107+
#### Removed methods
108+
109+
- `void com.auth0.client.mgmt.ManagementAPI#doNotSendTelemetry()` has been removed. Telemetry configuration can be done using the `DefaultHttpClient#Builder`
110+
- `void com.auth0.client.auth.AuthAPI#doNotSendTelemetry()` has been removed. Telemetry configuration can be done using the `DefaultHttpClient#Builder`
111+
- `void com.auth0.client.mgmt.ManagementAPI#setTelemetry(Telemetry telemetry)` has been removed. Telemetry configuration can be done using the `DefaultHttpClient#Builder`
112+
- `void com.auth0.client.auth.AuthAP#setTelemetry(Telemetry telemetry)` has been removed. Telemetry configuration can be done using the `DefaultHttpClient#Builder`
113+
- Deprecated `void com.auth0.client.mgmt.ManagementAPI#setLoggingEnabled(boolean enabled)` has been removed. Telemetry configuration can be done using the `DefaultHttpClient#Builder`
114+
- Deprecated `void com.auth0.client.auth.AuthAPI#setLoggingEnabled(boolean enabled)` has been removed. Telemetry configuration can be done using the `DefaultHttpClient#Builder`
115+
- Deprecated `Request<List<ClientGrant>> com.auth0.client.mgmt.ClientGrantsEntity#list()` has been removed. Use `Request<ClientGrantsPage> list(ClientGrantsFilter filter) com.auth0.client.mgmt.ClientGrantsEntity#list(ClientGrantsFilter filter)` instead.
116+
- Deprecated `Request<List<Client>> com.auth0.client.mgmt.ClientsEntity#list()` has been removed. Use `Request<ClientsPage> com.auth0.client.mgmt.ClientsEntity#list(ClientFilter filter)` instead.
117+
- Deprecated `Request<List<Connection>> com.auth0.client.mgmt.ClientsEntity#list(ConnectionFilter filter)` has been removed. Use `Request<ConnectionsPage> com.auth0.client.mgmt.ClientsEntity#listAll(ConnectionFilter filter)` instead.
118+
- Deprecated `Request<List<Grant>> com.auth0.client.mgmt.GrantsEntity#list(String userId)` has been removed. Use `Request<GrantsPage> com.auth0.client.mgmt.GrantsEntity#list(String userId, GrantsFilter filter)` instead.
119+
- Deprecated `Request<List<ResourceServer>> com.auth0.client.mgmt.ResourceServerEntity#list()` has been removed. Use `Request<ResourceServersPage> com.auth0.client.mgmt.ResourceServersEntity#list(ResourceServersFilter)` instead.
120+
- Deprecated `Request<List<Rule>> com.auth0.client.mgmt.RulesEntity#list(RulesFilter filter)` has been removed. Use `Request<RulesPage> com.auth0.client.mgmt.RulesEntity#listAll(RulesFilter filter)` instead.
121+
- Deprecated `void com.auth0.json.mgmt.guardian.EnrollmentTicket#setUserId(String id)` has been removed. Use the constructor instead.
122+
- Deprecated `com.auth0.json.mgmt.guardian.SNSFactorProvider` no-arg constructor has been removed. Use the full constructor instead.
123+
- Deprecated `void com.auth0.json.mgmt.guardian.SNSFactorProvider#setAWSAccessKeyId(String awsAccessKeyId)` has been removed. Use the constructor instead.
124+
- Deprecated `void com.auth0.json.mgmt.guardian.SNSFactorProvider#setAWSSecretAccessKey(String awsSecretAccessKey)` has been removed. Use the constructor instead.
125+
- Deprecated `void com.auth0.json.mgmt.guardian.SNSFactorProvider#setAWSRegion(String awsRegion)` has been removed. Use the constructor instead.
126+
- Deprecated `void com.auth0.json.mgmt.guardian.SNSFactorProvider#setSNSAPNSPlatformApplicationARN(String apnARN)` has been removed. Use the constructor instead.
127+
- Deprecated `void com.auth0.json.mgmt.guardian.SNSFactorProvider#setSNSGCMPlatformApplicationARN(String gcmARN)` has been removed. Use the constructor instead.
128+
- Deprecated `com.auth0.json.mgmt.guardian.TwilioFactorProvider` no-arg constructor has been removed. Use the full constructor instead.
129+
- Deprecated `void com.auth0.json.mgmt.guardian.TwilioFactorProvider#setFrom(String from)` has been removed. Use the constructor instead.
130+
- Deprecated `void com.auth0.json.mgmt.guardian.TwilioFactorProvider#setMessagingServiceSID(String messagingServiceSID)` has been removed. Use the constructor instead.
131+
- Deprecated `void com.auth0.json.mgmt.guardian.TwilioFactorProvider#setAuthToken(String authToken)` has been removed. Use the constructor instead.
132+
- Deprecated `void com.auth0.json.mgmt.guardian.TwilioFactorProvider#setSID(String SID)` has been removed. Use the constructor instead.
133+
- The default implementation of `com.auth0.net.Request#executeAsync()` has been removed; implementations must provide an implementation of `executeAsync`.
134+
135+
### New classes and methods
136+
137+
#### Refactored HTTP layer types
138+
139+
Version 2 introduces a new abstraction, `com.auth0.net.client.Auth0HttpClient`, to handle the core HTTP responsibilities of sending HTTP requests.
140+
An implementation is provided in `DefaultHttpClient`, which supports all the configurations available in the now-deprecated `HttpOptions`.
141+
In addition to these configurations, it is also possible to implement the `Auth0HttpClient` for advanced use-cases where the default implementation or its configurations are not sufficient.
142+
Several new types have been added to support this:
143+
144+
- `com.auth0.net.client.Auth0HttpClient` has been added to define the HTTP client interface.
145+
- `com.auth0.net.client.DefaultHttpClient` is the default HTTP implementation that should be used in the majority of cases. It supports the same configurations as `HttpOptions`, but can be reused across API clients. It uses `OkHttp` as the networking client internally.
146+
- `com.auth0.net.client.Auth0HttpRequest` is a lightweight representation of an HTTP request to execute. Internal API implementations will form the request.
147+
- `com.auth0.net.client.Auth0HttpResponse` is a lightweight representation of an HTTP response. Internal API implementations will parse the response.
148+
- `com.auth0.net.client.HttpMethod` is an `enum` representing the HTTP methods.
149+
150+
### New deprecations
151+
152+
- `com.auth0.client.HttpOptions` has been deprecated, in favor of configuring the `DefaultHttpClient` directly.
153+
- `com.auth0.client.mgmt.ManagementAPI` constructors have been deprecated in favor of `ManagementAPI#newBuilder(String domain, String apiToken)`.
154+
- `com.auth0.client.auth.AuthAPI` constructors have been deprecated in favor of `AuthAPI.newBuilder(String domain, String clientId)` and `AuthAPI.newBuilder(String domain, String clientId, String clientSecret)`.

0 commit comments

Comments
 (0)