Skip to content

Commit eca5a70

Browse files
mwj8410mwj8410
authored
chore(doc) add migration guide (#194)
* chore(doc) add migration guide * chore(doc) abstract documented current version number
1 parent b5c4873 commit eca5a70

1 file changed

Lines changed: 267 additions & 0 deletions

File tree

‎MIGRATION.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# Migrate from version < v13.0.0
2+
3+
This guide illustrates differences between Lob’s the legacy versions of this SDK and the new current version.
4+
5+
In this guide we compare how `v12.*.*` and >=`v13.0.0` implement the following method pattern.
6+
7+
- CREATE
8+
- LIST
9+
- GET
10+
- DELETE
11+
- VERIFY (BANK ACCOUNTS)
12+
- UPDATE (TEMPLATES)
13+
14+
## INSTALL
15+
16+
Similar to the legacy version, simply update your POM file dependency as follows:
17+
18+
```xml
19+
<dependency>
20+
<groupId>com.lob</groupId>
21+
<artifactId>lob-java</artifactId>
22+
<version>{{ CURRENT_VERSION_OF_JAVA }}</version>
23+
</dependency>
24+
```
25+
26+
If you are using the Spring framework, you will also need to add the following two blocks:
27+
```xml
28+
<dependencyManagement>
29+
<dependencies>
30+
<dependency>
31+
<groupId>com.squareup.okhttp3</groupId>
32+
<artifactId>okhttp</artifactId>
33+
<version>4.9.1</version>
34+
</dependency>
35+
</dependencies>
36+
</dependencyManagement>
37+
```
38+
and
39+
```xml
40+
<dependency>
41+
<groupId>com.squareup.okhttp3</groupId>
42+
<artifactId>okhttp</artifactId>
43+
<version>4.9.1</version>
44+
</dependency>
45+
```
46+
47+
## IMPORT AND INITIALIZE
48+
49+
```java
50+
import com.lob.api.ApiClient;
51+
import com.lob.api.ApiException;
52+
import com.lob.api.Configuration;
53+
import com.lob.api.auth.HttpBasicAuth;
54+
import com.lob.api.client.*;
55+
56+
public class Controller {
57+
private final ApiClient lobClient;
58+
59+
Controller() {
60+
ApiClient client = Configuration.getDefaultApiClient();
61+
HttpBasicAuth basicAuth = (HttpBasicAuth) client.getAuthentication("basicAuth");
62+
basicAuth.setUsername("<<YOUR API KEY HERE>>");
63+
64+
this.lobClient = client;
65+
}
66+
}
67+
```
68+
69+
You then instantiate the specific resource API that you need access to as follows:
70+
71+
```java
72+
AddressesApi apiInstance = new AddressesApi(this.lobClient);
73+
```
74+
75+
## METHODS
76+
77+
The new SDK version abstracts the request/response interaction out of the calling code such that you create the resource and pass it to the corresponding API in a try/catch such that any non-success is an `ApiException` that must be handled.
78+
79+
### COMPARE CREATE METHODS
80+
81+
Here is a sample of a legacy lob-java CREATE function:
82+
83+
```java
84+
LobResponse<Address> response = new Address.RequestBuilder()
85+
.setDescription("Harry - Office")
86+
.setName("Harry Zhang")
87+
.setCompany("Lob")
88+
.setLine1("210 King St")
89+
.setLine2("# 6100")
90+
.setCity("San Francisco")
91+
.setState("CA")
92+
.setZip("94107")
93+
.setCountry("US")
94+
.setPhone("555-555-5555")
95+
.setEmail("harry@lob.com")
96+
.create();
97+
98+
Address address = response.getResponseBody();
99+
```
100+
101+
Here is a sample of the updated CREATE method
102+
103+
```java
104+
try {
105+
AddressEditable address = new AddressEditable();
106+
address.setName("Harry Zhang");
107+
address.setCompany("Lob");
108+
address.setEmail("harry@lob.com");
109+
address.setPhone("5555555555");
110+
address.setAddressLine1("210 King St");
111+
address.setAddressLine2("# 6100");
112+
address.setAddressCity("San Francisco");
113+
address.setAddressState("CA");
114+
address.setAddressZip("94107");
115+
address.setAddressCountry(CountryExtended.US);
116+
117+
apiInstance.addressCreate(address);
118+
} catch (ApiException e) {
119+
e.printStackTrace();
120+
}
121+
```
122+
123+
### COMPARE CREATE METHODS WITH INLINE RECORDS
124+
125+
In these create operations, the required Address records are created alongside the record they are associated with.
126+
127+
```java
128+
LobResponse<Letter> response = new Letter.RequestBuilder()
129+
.setDescription("Demo Letter")
130+
.setFile("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/us_letter_1pg.pdf")
131+
.setColor(true)
132+
.setTo(
133+
new Address.RequestBuilder()
134+
.setName("Harry Zhang")
135+
.setLine1("210 King St Ste 6100")
136+
.setCity("San Francisco")
137+
.setState("CA")
138+
.setZip("94107")
139+
)
140+
.setFrom("adr_210a8d4b0b76d77b")
141+
.create();
142+
143+
Letter letter = response.getResponseBody();
144+
```
145+
146+
The same letter can be created as follows:
147+
148+
```java
149+
try {
150+
AddressEditable addressTo = new AddressEditable();
151+
addressTo.setName("Harry Zhang");
152+
addressTo.setAddressLine1("210 King St");
153+
addressTo.setAddressLine2("# 6100");
154+
addressTo.setAddressCity("San Francisco");
155+
addressTo.setAddressState("CA");
156+
addressTo.setAddressZip("94107");
157+
158+
LetterEditable letterRaw = new LetterEditable();
159+
letterRaw.setDescription("Demo Letter");
160+
letterRaw.setTo(addressTo);
161+
letterRaw.setFrom("adr_210a8d4b0b76d77b");
162+
letterRaw.setFile("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/us_letter_1pg.pdf");
163+
letterRaw.setColor(true);
164+
165+
Letter letter = apiInstance.create(letterRaw, null);
166+
} catch (ApiException e) {
167+
e.printStackTrace();
168+
}
169+
```
170+
171+
### COMPARE LIST METHODS
172+
173+
Here is a sample of a legacy lob-java LIST method:
174+
175+
```java
176+
Map<String, Object> params = new HashMap<>();
177+
params.put("limit", 2);
178+
179+
LobResponse<AddressCollection> response = Address.list(params);
180+
AddressCollection addresses = response.getResponseBody();
181+
```
182+
183+
Here is a sample of the updated LIST method:
184+
185+
```java
186+
try {
187+
AddressList addresses = apiInstance.list(2, null, null, null, null, null);
188+
} catch (ApiException e) {
189+
e.printStackTrace();
190+
}
191+
```
192+
193+
### COMPARE GET BY ID METHOD
194+
195+
Here is a sample of a legacy GET method:
196+
197+
```java
198+
LobResponse<Address> response = Address.retrieve("adr_fa85158b26c3eb7c");
199+
Address address = response.getResponseBody();
200+
```
201+
202+
Here is a sample of the updated SDK GET by ID method:
203+
204+
```java
205+
try {
206+
Address address = apiInstance.get("adr_fa85158b26c3eb7c");
207+
} catch (ApiException e) {
208+
e.printStackTrace();
209+
}
210+
```
211+
212+
### COMPARE DELETE METHOD
213+
214+
Here is a sample of the legacy DELETE method:
215+
216+
```java
217+
LobResponse<Address> response = Address.delete("adr_43769b47aed248c2");
218+
Address address = response.getResponseBody();
219+
```
220+
221+
Here is a sample of the updated SDK DELETE method:
222+
223+
```java
224+
try {
225+
AddressDeletion address = apiInstance.delete("adr_fa85158b26c3eb7c");
226+
} catch (ApiException e) {
227+
e.printStackTrace();
228+
}
229+
```
230+
231+
### COMPARE BANK ACCOUNT VERIFY
232+
233+
​Here is a sample of the legacy Bank Account Verify method
234+
235+
```java
236+
LobResponse<BankAccount> response = BankAccount.verify(newBankAccount.getId(), Arrays.asList(25, 63));
237+
BankAccount bankAccount = response.getResponseBody();
238+
```
239+
240+
Here is a sample of the updated SDK Bank Account Verify method:
241+
242+
```java
243+
try {
244+
BankAccountVerify verification = new BankAccountVerify();
245+
verification.addAmountsItem(11);
246+
verification.addAmountsItem(35);
247+
BankAccount account = apiInstance.verify("bank_8cad8df5354d33f", verification);
248+
} catch (ApiException e) {
249+
e.printStackTrace();
250+
}
251+
```
252+
253+
### TEMPLATE UPDATE METHOD
254+
255+
The Template Update endpoint updates the description and/or published version of the template with a given id. This is how it is done:
256+
257+
```java
258+
try {
259+
TemplateUpdate templateUpdate = new TemplateUpdate();
260+
templateUpdate.setDescription("Updated Example");
261+
templateUpdate.setPublishedVersion("vrsn_a");
262+
263+
Template template = apiInstance.update("tmpl_c94e83ca2cd5121", templateUpdate);
264+
} catch (ApiException e) {
265+
e.printStackTrace();
266+
}
267+
```

0 commit comments

Comments
 (0)