Skip to content

Commit 6f6394a

Browse files
mohnoor94mohnoor94
authored
feat: add devhub rapid sdk docs (#240)
1 parent 8688d91 commit 6f6394a

File tree

14 files changed

+1238
-0
lines changed

14 files changed

+1238
-0
lines changed

‎docs/assets/maven_refresh.png‎

1.25 MB
Loading

‎docs/java/exception-handling.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
intro: Exception handling in the Rapid SDK for Java
3+
shortTitle: Exception handling
4+
title: Exception handling
5+
---
6+
7+
# Exception Handling in the Rapid SDK for Java
8+
9+
#### A guide to exception handling in the Rapid SDK for Java
10+
11+
The Rapid SDK for Java uses runtime (unchecked) exceptions to relay errors. At the root of the exception hierarchy is `ExpediaGroupException` from which all other exceptions are extended. `ExpediaGroupException` is never thrown directly.
12+
13+
There are two categories of `ExpediaGroupException`:
14+
15+
1. `ExpediaGroupServiceException`: Thrown when the downstream service returns an error response. That is, the service successfully received the request but it was not able to process it. The exception object provides the caller with several pieces of information about the error including an HTTP status code and a detailed message. `ExpediaGroupAuthException` is a subtype of this exception and it is thrown when authentication fails.
16+
17+
2. `ExpediaGroupClientException`: Thrown at client errors, either when trying to send the request or parse the response. For example, an `ExpediaGroupConfigurationException` is thrown if credentials are not configured.
18+
19+
Since exceptions are unchecked, the caller decides which exceptions to handle. In principle, an `ExpediaGroupClientException` is assumed to be not retryable and should typically be fixed during development. On the other hand, an `ExpediaGroupServiceException` might be recoverable, such as errors resulting from a service being temporarily unavailable. Error handling should therefore focus on the latter.

‎docs/java/index.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Rapid SDK developer guide
3+
shortTitle: SDK
4+
intro: Rapid SDK developer guide
5+
---
6+
7+
# Rapid SDK Developer Guide
8+
9+
#### The Rapid SDK makes integrating simple, saving development time so you can focus more on getting your product to market and less on the technical details of the API.
10+
11+
### SDK overview
12+
13+
**What is an SDK?**
14+
15+
In a nutshell, a software development kit (SDK) is a collection of software development tools in one easily installable package. By taking advantage of the Rapid SDK partners can streamline their integration journey and remove the need to build functionality from scratch.
16+
17+
**What's the difference between an SDK and an API?**
18+
19+
An SDK provides developers with documentation, APIs, code samples, and libraries and processes. All the essential building blocks for the software product.
20+
21+
By contrast, an API only provides the necessary code that allows two software programs to communicate and share information with one another. As such, at least one API is often included in an SDK because, without an API, applications can’t relay information and work together.
22+
23+
**What are the advantages of using an SDK?**
24+
25+
- **Efficiency.** SDKs let developers easily build the standard components of their apps and add functionality to them without having to build everything from the ground up themselves.
26+
- **Simplified integration.** SDKs reduce the complexity of integrations by simplifying standard processes.
27+
- **Documentation and code libraries.** SDKs include a variety of resources including documentation and code samples that developers can use to build and maintain applications.
28+
- **Enhanced functionality.** SDKs help developers enhance apps with more functionality or create new tools.
29+
- **Cost savings.** SDKs speed up the development process and make it quicker to get new apps to market meaning apps built with SDKs can offer substantial cost savings. SDK integrations also don't require specialized technical skills meaning partners can perform in-house integrations without needing outside professionals.
30+
- **Customization.** SDKs offer partners the opportunity to develop apps with personalized user experiences.
31+
32+
You can find a step-by-step guide to using the Rapid SDK for your integration [here](products/rapid/sdk/java/quick-start).

‎docs/java/links.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
intro: Introducing Links
3+
shortTitle: Introducing Links
4+
title: Introducing Links
5+
tags:
6+
- new
7+
---
8+
9+
# Introducing Links
10+
11+
## What is a Link?
12+
13+
RapidAPI consists of several API resources that enable you to create an end-to-end booking experience for your
14+
travelers.
15+
This means you'll use these resources in sequence to build complete transactions, such as **shopping**,
16+
**price checking**, **booking**, and **managing bookings**.
17+
18+
To streamline these multistep transactions, RapidAPI employs a powerful tool called `Link`.
19+
20+
A `Link` is a reference to a related resource, acting as a guide that directs developers to the next relevant API
21+
resource needed to seamlessly progress through the transaction.
22+
23+
By leveraging Links from previous operations within the Rapid SDK, developers can swiftly create and execute new
24+
operations, bypassing the typical setup process and significantly enhancing efficiency.
25+
26+
{% messageCard type="info" %}
27+
{% messageCardHeader %}
28+
Note
29+
{% /messageCardHeader %}
30+
This feature is available in the `rapid-sdk` v4.3.0 and later.
31+
{% /messageCard %}
32+
33+
## Why to use a Link?
34+
35+
`Link` is a convenient way to navigate through the Rapid API operations, without having to manually create the next
36+
operation. You can extract a `Link` from the response of the previous operation and use it to create the next operation.
37+
38+
A link will benefit you in the following ways:
39+
40+
- **Saves time:** You don't have to manually create the next operation by setting up the request parameters and the
41+
operation.
42+
- **Simplifies the process:** You can easily navigate through the Rapid API operations by using the `Link` from the
43+
previous operation, without having to extract the needed information manually.
44+
- **Reduces errors:** By using the `Link`, you can avoid errors that might occur when manually creating the next
45+
operation.
46+
47+
## How to use a Link?
48+
49+
To get a `Link`, you need to extract it from the previous `Operation` response.
50+
Then, you can create the next `Operation` from the `Link` and execute it with the `RapidClient`.
51+
52+
For example, you can create a `Link` from the response of a `GetAvailabilityOperation` and use it in creating
53+
a `PriceCheckOperation`:
54+
55+
```java
56+
// 1. Create and execute the GetAvailabilityOperation (The first operation)
57+
GetAvailabilityOperation getAvailabilityOperation = new GetAvailabilityOperation(getAvailabilityOperationParams);
58+
Response<List<Property>> propertiesResponse = rapidClient.execute(getAvailabilityOperation);
59+
60+
// 2a. Select the needed property from the response (Here, we select the first property)
61+
Property property = propertiesResponse.getData().get(0);
62+
63+
// 2b. Make sure the property is an instance of PropertyAvailability
64+
if (!(property instanceof PropertyAvailability)) {
65+
return;
66+
}
67+
68+
PropertyAvailability propertyAvailability = (PropertyAvailability) property;
69+
70+
// 3a. Extract the priceCheck link from PropertyAvailability operation (Here, we select the first rate for the first room, then get the priceCheck link)
71+
Link priceCheckLink = propertyAvailability.getRooms().get(0).getRates().get(0).getBedGroups().entrySet().stream().findFirst().get().getValue().getLinks().getPriceCheck();
72+
73+
// 3b. Create the needed context for the PriceCheckOperation
74+
PriceCheckOperationContext priceCheckOperationContext = PriceCheckOperationContext.builder().customerIp("1.2.3.4").build(); // fill the context as needed
75+
76+
// 4. Create and execute the PriceCheckOperation using the Link
77+
PriceCheckOperation priceCheckOperation = new PriceCheckOperation(priceCheckLink, priceCheckOperationContext);
78+
Response<RoomPriceCheck> roomPriceCheckResponse = rapidClient.execute(priceCheckOperation);
79+
// ...
80+
```
81+
82+
Another example would be to create a `Link` from the response of a `PriceCheckOperation` and use it in creating a
83+
booking.
84+
85+
```java
86+
// 1. Get the RoomPriceCheck from the previous step
87+
RoomPriceCheck roomPriceCheck = roomPriceCheckResponse.getData(); // from the previous step
88+
89+
// 2a. Extract the Link from the RoomPriceCheck
90+
Link postItineraryLink = roomPriceCheck.getLinks().getBook();
91+
92+
// 2b. Create the needed context for the PostItineraryOperation
93+
PostItineraryOperationContext postItineraryOperationContext = PostItineraryOperationContext.builder().customerIp("1.2.3.4").build(); // fill the context as needed
94+
95+
// 2c. Create the CreateItineraryRequest
96+
CreateItineraryRequest createItineraryRequest = CreateItineraryRequest.builder().build(); // fill the request as needed
97+
98+
// 3. Create and execute the PostItineraryOperation using the Link
99+
PostItineraryOperation postItineraryOperation = new PostItineraryOperation(postItineraryLink, postItineraryOperationContext, createItineraryRequest);
100+
101+
// 4. Execute the PostItineraryOperation
102+
Response<ItineraryCreation> itineraryCreationResponse = rapidClient.execute(postItineraryOperation);
103+
ItineraryCreation itineraryCreation = itineraryCreationResponse.getData();
104+
```
105+
106+
For more examples on how to use `Link`, see the [Usage Examples](products/rapid/sdk/java/usage-examples) section.
107+

‎docs/java/logging.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
intro: Logging in the Rapid SDK for Java
3+
shortTitle: Logging
4+
title: Logging in the Rapid SDK for Java
5+
---
6+
7+
# Logging in the Rapid SDK for Java
8+
9+
The Rapid SDK for Java does not impose a logging framework on clients and instead supports logging via the [SLF4J](https://www.slf4j.org/) interface. SLF4J provides an abstraction for various logging frameworks, allowing clients to plug in their desired implementation when building their projects.
10+
11+
Without a logging framework plugged in, the SDK (SLF4J) defaults to a no-operation, discarding all log requests with a single warning message:
12+
13+
```
14+
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".\
15+
SLF4J: Defaulting to no-operation (NOP) logger implementation\
16+
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
17+
```
18+
19+
## Declaring project dependencies
20+
21+
A client can plug in a particular logging framework by declaring it as a project dependency. By design, SLF4J can use only one framework at a time and it will emit a warning message if it finds multiple frameworks.
22+
23+
### Simple logger
24+
25+
{% tabs code=true group="buildTools" %}
26+
{% tab label="Maven" %}
27+
28+
```xml
29+
<dependency>
30+
<groupId>org.slf4j</groupId>
31+
<artifactId>slf4j-simple</artifactId>
32+
<!-- version -->
33+
</dependency>
34+
```
35+
36+
{% /tab %}
37+
{% tab label="Gradle" %}
38+
39+
```gradle
40+
dependencies {
41+
implementation group: 'org.slf4j', name: 'slf4j-simple'
42+
}
43+
```
44+
45+
{% /tab %}
46+
{% /tabs %}
47+
48+
### Java Util logging
49+
50+
{% tabs code=true group="buildTools" %}
51+
{% tab label="Maven" %}
52+
53+
```xml
54+
<dependency>
55+
<groupId>org.slf4j</groupId>
56+
<artifactId>slf4j-jdk14</artifactId>
57+
<!-- version -->
58+
</dependency>
59+
```
60+
61+
{% /tab %}
62+
{% tab label="Gradle" %}
63+
64+
```gradle
65+
dependencies {
66+
implementation group: 'org.apache.logging.log4j', name: 'log4j-api'
67+
}
68+
```
69+
70+
{% /tab %}
71+
{% /tabs %}
72+
73+
### Logback
74+
75+
{% tabs code=true group="buildTools" %}
76+
{% tab label="Maven" %}
77+
78+
```xml
79+
<dependency>
80+
<groupId>ch.qos.logback</groupId>
81+
<artifactId>logback-classic</artifactId>
82+
<!-- version -->
83+
</dependency>
84+
```
85+
86+
{% /tab %}
87+
{% tab label="Gradle" %}
88+
89+
```gradle
90+
dependencies {
91+
implementation group: 'ch.qos.logback', name: 'logback-classic'
92+
}
93+
```
94+
95+
{% /tab %}
96+
{% /tabs %}
97+
98+
### Log4j2
99+
100+
{% tabs code=true group="buildTools" %}
101+
{% tab label="Maven" %}
102+
103+
```xml
104+
<dependency>
105+
<groupId>org.apache.logging.log4j</groupId>
106+
<artifactId>log4j-api</artifactId>
107+
<!-- version -->
108+
</dependency>
109+
<dependency>
110+
<groupId>org.apache.logging.log4j</groupId>
111+
<artifactId>log4j-core</artifactId>
112+
<!-- version -->
113+
</dependency>
114+
<dependency>
115+
<groupId>org.apache.logging.log4j</groupId>
116+
<artifactId>log4j-slf4j-impl</artifactId>
117+
<!-- version -->
118+
</dependency>
119+
```
120+
121+
{% /tab %}
122+
{% tab label="Gradle" %}
123+
124+
```gradle
125+
dependencies {
126+
implementation group: 'org.apache.logging.log4j', name: 'log4j-api'
127+
implementation group: 'org.apache.logging.log4j', name: 'log4j-core'
128+
implementation group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl'
129+
}
130+
```
131+
132+
{% /tab %}
133+
{% /tabs %}
134+
135+
## Log format
136+
137+
Logging frameworks support custom log formatting and layouts and including details such as the timestamp and the logger name at the origin of the logging event helps troubleshoot the SDK. In addition, log messages are annotated with the prefix `ExpediaGroupSDK` against which they could be filtered out.
138+
139+
```log
140+
13:36:59.287 [DefaultDispatcher-worker-1] INFO c.e.s.c.c.c.ConfigurationCollector MDC= - ExpediaSDK: Successfully loaded [endpoint] from [runtime configuration]
141+
```
142+
143+
## Log levels
144+
145+
If you want to keep track of request and response data originating from and received by the SDK, you can set your log level at INFO, which would log them including header and body content; however, this could generate a significant amount of logging data. Setting the log level to WARN or ERROR would only log exceptions and errors which would still include a transaction ID that you can share with Expedia Group in case of unexpected behavior.
146+
147+
If you are troubleshooting an issue, you can set the log level to DEBUG to get more detailed information about the request and response, the logs at the DEBUG level include more verbose logging of the OkHttp client events and the transaction ID.
148+
149+
Example log messages at the DEBUG level:
150+
151+
```log
152+
17:40:08.490 [DefaultDispatcher-worker-3] DEBUG com.expediagroup.sdk.core.client.OkHttpEventListener - ExpediaSDK: Call start for transaction-id: [aff4c00d-6f79-4690-8f60-dd1aaccbfaee]
153+
17:40:08.496 [OkHttp https://test.ean.com/...] DEBUG com.expediagroup.sdk.core.client.OkHttpEventListener - ExpediaSDK: Connect start for transaction-id: [aff4c00d-6f79-4690-8f60-dd1aaccbfaee]
154+
17:40:08.508 [OkHttp https://test.ean.com/...] DEBUG com.expediagroup.sdk.core.client.OkHttpEventListener - ExpediaSDK: Connect end for transaction-id: [aff4c00d-6f79-4690-8f60-dd1aaccbfaee]
155+
17:40:08.508 [OkHttp https://test.ean.com/...] DEBUG com.expediagroup.sdk.core.client.OkHttpEventListener - ExpediaSDK: Connection acquired for transaction-id: [aff4c00d-6f79-4690-8f60-dd1aaccbfaee]
156+
17:40:08.510 [OkHttp https://test.ean.com/...] DEBUG com.expediagroup.sdk.core.client.OkHttpEventListener - ExpediaSDK: Sending request headers start for transaction-id: [aff4c00d-6f79-4690-8f60-dd1aaccbfaee]
157+
17:40:08.510 [OkHttp https://test.ean.com/...] DEBUG com.expediagroup.sdk.core.client.OkHttpEventListener - ExpediaSDK: Sending request headers end for transaction-id: [aff4c00d-6f79-4690-8f60-dd1aaccbfaee]
158+
```
159+
160+
## Traceability
161+
162+
The SDK generates a unique `transaction ID` for every API call, which is useful for troubleshooting issues by tracing requests end-to-end. The transactions IDs are added to the request and response headers, and they are logged in error messages in case of exceptions.

0 commit comments

Comments
 (0)