Skip to content

Commit 42b5c47

Browse files
flinchyciwowo-reloadlyDoctor-Vee
authored
Feature/documentation sync (#10)
* ➕ modify SAMPLE-CODE.md * ➕ add git ignore file * ➕ add starter code * ✨ clean up code * Feature/usage and discount operations (#12) * ✨ add correct return value * ✨ add documentation for giftcard discount operations * ✨ add usage for Giftcard Api * ✨ modify SAMPLE-CODE.md * ✨ remove whitespaces in USAGE.md Co-authored-by: chisomiwowo <ciwowo@reloadly.com> * Feature/order and product operations (#11) * 💻 prepare the documentation for order and product operations * 💄 clean up * ➕ Add links to SAMPLE-CODE.MD * 💄 rename doc * 💄 modify text * 💄 modify text * ➕ add method documentation for redeem instructions * ➕ add documentation for transactions operations Co-authored-by: DoctorVee <vchinewubeze@reloadly.com> Co-authored-by: chisomiwowo <ciwowo@reloadly.com> Co-authored-by: chisomiwowo <ciwowo@reloadly.com> Co-authored-by: Doctor Vee <victor.chinewubeze@gmail.com> Co-authored-by: DoctorVee <vchinewubeze@reloadly.com>
1 parent b2e8a4c commit 42b5c47

9 files changed

+857
-2
lines changed

‎SAMPLE-CODE.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,13 @@
1313
* [Operator Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-airtime/usage/OPERATOR-OPERATIONS.md)
1414
* [Promotion Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-airtime/usage/PROMOTION-OPERATIONS.md)
1515
* [Report Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-airtime/usage/REPORT-OPERATIONS.md)
16-
* [Topup Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-airtime/usage/TOPUP-OPERATIONS.md)
16+
* [Topup Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-airtime/usage/TOPUP-OPERATIONS.md)
17+
18+
## Giftcard SDK
19+
20+
* [Overview](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-giftcard/USAGE.md) (You should start here)
21+
* [Giftcard Discount Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-giftcard/usage/GIFTCARD-DISCOUNT-OPERATIONS.md)
22+
* [Giftcard Order Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-giftcard/GIFTCARD-ORDER-OPERATIONS.md)
23+
* [Giftcard Products Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-giftcard/GIFTCARD-PRODUCTS-OPERATIONS.md)
24+
* [Giftcard Redeem Instructions Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-giftcard/GIFTCARD-REDEEM-INSTRUCTIONS-OPERATIONS.md)
25+
* [Giftcard Transactions Operations](https://github.com/Reloadly/reloadly-sdk-java/blob/main/java-sdk-giftcard/GIFTCARD-TRANSACTIONS-OPERATIONS.md)

‎java-sdk-airtime/usage/DISCOUNT-OPERATIONS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ try {
9090
// api error retrieving access_token
9191
}
9292

93-
Page<Discount> discount = null;
93+
Discount discount = null;
9494
try {
9595
discount = request.execute();
9696
} catch (APIException e) {

‎java-sdk-giftcard/.gitignore

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
target/
2+
!.mvn/wrapper/maven-wrapper.jar
3+
4+
### STS ###
5+
.apt_generated
6+
.classpath
7+
.factorypath
8+
.project
9+
.settings
10+
.springBeans
11+
12+
### IntelliJ IDEA ###
13+
.idea
14+
*.iws
15+
*.iml
16+
*.ipr
17+
18+
### NetBeans ###
19+
nbproject/private/
20+
build/
21+
nbbuild/
22+
dist/
23+
nbdist/
24+
.nb-gradle/
25+
26+
# OS generated files #
27+
######################
28+
.DS_Store
29+
.DS_Store?

‎java-sdk-giftcard/USAGE.md

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# Giftcard API
2+
3+
The implementation is based on the [Giftcard API Docs](https://docs.reloadly.com/giftcards/).
4+
5+
## Usage
6+
Create a `GiftcardAPI` instance by providing the Application details (client id & secret) from
7+
the [dashboard](https://www.reloadly.com/developers/api-settings).
8+
9+
Some key things to keep in mind regarding the Gitfcard API :
10+
11+
* The API has 2 environments, SANDBOX (for development & testing) and LIVE.
12+
* If neither environment is specified, the SDK defaults to SANDBOX.
13+
* Each environment has a set of credentials (client id & secret) that are different from the other.<br />
14+
* SANDBOX credentials can only be used for SANDBOX environment.
15+
* LIVE credentials can only be used for LIVE environment.
16+
* If no environment is specified, the SDK defaults to SANDBOX.
17+
* You MUST supply either the credentials, or an access token in order to call the API
18+
<br /><br />
19+
20+
As stated above, requests to the Giftcard API require authentication/authorization, there are several options :
21+
22+
### Option 1
23+
24+
Set the `client id` & `client secret`; this is probably the most straight-forward or simplest way. An `access token` will be
25+
acquired automatically before the API call is made.
26+
27+
```java
28+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
29+
.clientId(clientId)
30+
.clientSecret(clientSecret)
31+
.environment(Environment.SANDBOX) //Giftcard service has 2 environments, LIVE and SANDBOX. If not environment is specified, the SDK defaults to SANDBOX
32+
.build();
33+
34+
Long productId = 174L; //From GiftcardProduct.id
35+
Request<GiftcardDiscount> request;
36+
37+
try {
38+
request = giftcardAPI.discounts().getByProductId(productId);
39+
} catch (ReloadlyException e) {
40+
// api error retrieving access_token
41+
}
42+
43+
GiftcardDiscount discount = null;
44+
try {
45+
discount = request.execute();
46+
} catch (APIException e) {
47+
// api error
48+
} catch (ReloadlyException e) {
49+
// request error
50+
} catch (Exception e) {
51+
// all others
52+
}
53+
```
54+
55+
### Option 2
56+
57+
You may alternatively acquire an `access token` from the
58+
[AuthenticationAPI](https://github.com/reloadly/reloadly-sdk-java/blob/master/reloadly-java-sdk-authentication/USAGE.md)
59+
and then set it.
60+
61+
```java
62+
OAuth2ClientCredentialsRequest tokenRequest = AuthenticationAPI.builder()
63+
.clientId(clientId)
64+
.clientSecret(clientSecret)
65+
.service(Service.GIFTCARD_SANDBOX)
66+
.build()
67+
.clientCredentials()
68+
.getAccessToken();
69+
70+
TokenHolder tokenHolder = null;
71+
try {
72+
tokenHolder = tokenRequest.execute();
73+
} catch (APIException e) {
74+
// api error
75+
} catch (ReloadlyException e) {
76+
// request error
77+
} catch (Exception e) {
78+
// all others
79+
}
80+
81+
Request<GiftcardDiscount> request = GiftcardAPI.builder()
82+
.clientId(clientId)
83+
.clientSecret(clientSecret)
84+
.accessToken(tokenHolder.getAccessToken()) //Set the access token to be used by here
85+
.environment(Environment.SANDBOX)
86+
.build()
87+
.discounts().getByProductId(productId);
88+
89+
GiftcardDiscount discount = null;
90+
try {
91+
discount = request.execute();
92+
} catch (APIException e) {
93+
// api error
94+
} catch (ReloadlyException e) {
95+
// request error
96+
} catch (Exception e) {
97+
// all others
98+
}
99+
```
100+
101+
**Note : Access tokens obtained for Reloadly APIs have a finite
102+
lifetime. [See the API docs](https://developers.reloadly.com/#authentication_auth_anc)**
103+
104+
Using the example above has some benefits and drawbacks:
105+
106+
#### Pro
107+
108+
* API requests become efficient & performant.
109+
* Setting the access token skips the automatic token acquisition API calls that would have otherwise been made before
110+
each Airtime API service calls.
111+
112+
#### Cons
113+
114+
* However, because access tokens have a finite lifetime, you now have to manage or handle the expiration of the access
115+
token in your application code.
116+
* In the sample above, the `GiftcardAPI` will continue using the same access token until it expires. Therefore, the
117+
responsibility false on you to handle token renewal when the token expires.
118+
119+
### Sample token expiration handling
120+
121+
```java
122+
//Retrieve token using AuthenticationAPI
123+
OAuth2ClientCredentialsRequest tokenRequest = AuthenticationAPI.builder()
124+
.clientId(clientId)
125+
.clientSecret(clientSecret)
126+
.service(Service.GIFTCARD_SANDBOX)
127+
.build()
128+
.clientCredentials()
129+
.getAccessToken();
130+
131+
TokenHolder tokenHolder = null;
132+
try {
133+
tokenHolder = tokenRequest.execute();
134+
} catch (APIException e) {
135+
// api error
136+
} catch (ReloadlyException e) {
137+
// request error
138+
} catch (Exception e) {
139+
// all others
140+
}
141+
142+
Request<GiftcardDiscount> request = GiftcardAPI.builder()
143+
.clientId(clientId)
144+
.clientSecret(clientSecret)
145+
.accessToken(tokenHolder.getAccessToken()) //Set the access token to be used by here
146+
.environment(Environment.SANDBOX)
147+
.build()
148+
.discounts().getByProductId(productId);
149+
150+
GiftcardDiscount discount = null;
151+
try {
152+
discount = request.execute();
153+
} catch (APIException e) {
154+
if (e.getErrorCode().equals("TOKEN_EXPIRED")) {//Refresh the access token if it's expired
155+
giftcardAPI.refreshAccessToken(request);
156+
discount = request.execute(); //Re-execute the request
157+
} else {
158+
//Handle other errors....
159+
}
160+
} catch (ReloadlyException e) {
161+
// request error
162+
} catch (Exception e) {
163+
// all others
164+
}
165+
```
166+
167+
### Logging request & response
168+
169+
To enable API request/response logging
170+
171+
```java
172+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
173+
.enableLogging(true)
174+
.redactHeaders(Collections.singletonList(HttpHeader.AUTHORIZATION)) //Prevent the access token from being displayed in the logs
175+
....
176+
```
177+
178+
## Customizing The API Client Instance
179+
180+
### Configuring Timeouts
181+
182+
Used to configure additional options, connect and read timeouts can be configured globally:
183+
184+
```java
185+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
186+
.options(HttpOptions.builder()
187+
.readTimeout(Duration.ofSeconds(60))
188+
.writeTimeout(Duration.ofSeconds(60))
189+
.connectTimeout(Duration.ofSeconds(60)).build()
190+
)
191+
....
192+
```
193+
194+
### Proxy Configuration
195+
196+
```java
197+
int proxyPort = 8085; //Your proxy port
198+
String username = "your-proxy-authentication-username"; //Optional proxy username if your proxy requires authentication
199+
String password = "your-proxy-authentication-password"; //Optional proxy password if your proxy requires authentication
200+
String proxyHost = "you-proxy-host-name.com";
201+
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(proxyHost, proxyPort));
202+
203+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
204+
.options(HttpOptions.builder()
205+
.proxyOptions(new ProxyOptions(proxy, username, password.toCharArray()))
206+
.build()
207+
)
208+
....
209+
210+
//If proxy does NOT require authentication
211+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
212+
.options(HttpOptions.builder()
213+
.proxyOptions(new ProxyOptions(proxy))
214+
.build()
215+
)
216+
....
217+
```
218+
219+
### Request latency telemetry
220+
221+
By default, the library sends request latency telemetry to `Reloadly`. These numbers help `Reloadly` improve the overall
222+
latency of its API for all users.
223+
224+
You can disable this behavior if you prefer:
225+
226+
```java
227+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
228+
.enableTelemetry(false)
229+
....
230+
```

‎java-sdk-giftcard/usage/GIFTCARD-DISCOUNT-OPERATIONS.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Giftcard Discounts Operations
2+
3+
Discounts or commissions are a way for you to check what percentage discount rate you will get for each **Giftcard
4+
Product** when you make a successful order. These operations can be used to calculate your profits. All Commissions are
5+
paid instantly when an order is processed.
6+
7+
Thing to note on the response are the fields **global**, which indicate if the gift card can be used globally across
8+
different countries, and **percentage**, which indicates the percentage discount available for every purchase of the
9+
gift card.
10+
11+
## Giftcard Discounts - List
12+
13+
```java
14+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
15+
.clientId(clientId)
16+
.clientSecret(clientSecret)
17+
.environment(Environment.SANDBOX)
18+
.build();
19+
20+
Request<Page<GiftcardDiscount>> request;
21+
try {
22+
request = giftcardAPI.discounts().list();
23+
} catch (ReloadlyException e) {
24+
// api error retrieving access_token
25+
}
26+
27+
Page<GiftcardDiscount> discountPage = null;
28+
try {
29+
discountPage = request.execute();
30+
} catch (APIException e) {
31+
// api error
32+
} catch (ReloadlyException e) {
33+
// request error
34+
} catch (Exception e) {
35+
// all others
36+
}
37+
```
38+
39+
## Giftcard Discounts - Get by product id
40+
41+
```java
42+
GiftcardAPI giftcardAPI = GiftcardAPI.builder()
43+
.clientId(clientId)
44+
.clientSecret(clientSecret)
45+
.environment(Environment.SANDBOX)
46+
.build();
47+
48+
Long productId = 174L; //From GiftcardProduct.id
49+
Request<GiftcardDiscount> request;
50+
51+
try {
52+
request = giftcardAPI.discounts().getByProductId(productId);
53+
} catch (ReloadlyException e) {
54+
// api error retrieving access_token
55+
}
56+
57+
GiftcardDiscount discount = null;
58+
try {
59+
discount = request.execute();
60+
} catch (APIException e) {
61+
// api error
62+
} catch (ReloadlyException e) {
63+
// request error
64+
} catch (Exception e) {
65+
// all others
66+
}
67+
```

0 commit comments

Comments
 (0)