0
# HTTP Clients
1

2
Pluggable HTTP client implementations for making requests to AWS services. The AWS SDK provides multiple HTTP client implementations allowing you to choose the best option based on your application's requirements and runtime environment.
3

4
## Core Imports
5

6
```xml
7
<!-- Import BOM for version management -->
8
<dependencyManagement>
9
    <dependencies>
10
        <dependency>
11
            <groupId>software.amazon.awssdk</groupId>
12
            <artifactId>bom</artifactId>
13
            <version>2.33.4</version>
14
            <type>pom</type>
15
            <scope>import</scope>
16
        </dependency>
17
    </dependencies>
18
</dependencyManagement>
19
```
20

21
## Capabilities
22

23
### Netty NIO Client
24

25
Asynchronous HTTP client implementation based on Netty NIO for high-performance non-blocking operations.
26

27
```xml { .api }
28
/**
29
 * Netty-based NIO HTTP client for asynchronous operations
30
 * Best for: High-throughput applications, async/reactive programming
31
 * Features: Non-blocking I/O, connection pooling, HTTP/2 support
32
 */
33
<dependency>
34
    <groupId>software.amazon.awssdk</groupId>
35
    <artifactId>netty-nio-client</artifactId>
36
    <version>${awsjavasdk.version}</version>
37
</dependency>
38
```
39

40
**Usage Example:**
41

42
```xml
43
<dependencies>
44
    <!-- Service client -->
45
    <dependency>
46
        <groupId>software.amazon.awssdk</groupId>
47
        <artifactId>s3</artifactId>
48
    </dependency>
49
    
50
    <!-- Netty HTTP client -->
51
    <dependency>
52
        <groupId>software.amazon.awssdk</groupId>
53
        <artifactId>netty-nio-client</artifactId>
54
    </dependency>
55
</dependencies>
56
```
57

58
### Apache HTTP Client
59

60
Traditional Apache HTTP client implementation for blocking operations with extensive configuration options.
61

62
```xml { .api }
63
/**
64
 * Apache HTTP client implementation for synchronous operations
65
 * Best for: Traditional blocking applications, extensive HTTP customization
66
 * Features: Mature ecosystem, comprehensive configuration, proxy support
67
 */
68
<dependency>
69
    <groupId>software.amazon.awssdk</groupId>
70
    <artifactId>apache-client</artifactId>
71
    <version>${awsjavasdk.version}</version>
72
</dependency>
73
```
74

75
**Usage Example:**
76

77
```xml
78
<dependencies>
79
    <!-- Service client -->
80
    <dependency>
81
        <groupId>software.amazon.awssdk</groupId>
82
        <artifactId>dynamodb</artifactId>
83
    </dependency>
84
    
85
    <!-- Apache HTTP client -->
86
    <dependency>
87
        <groupId>software.amazon.awssdk</groupId>
88
        <artifactId>apache-client</artifactId>
89
    </dependency>
90
</dependencies>
91
```
92

93
### Apache HTTP 5 Client (Preview)
94

95
Next-generation Apache HTTP client implementation with modern features and improved performance.
96

97
```xml { .api }
98
/**
99
 * Apache HTTP 5 client implementation (Preview version)
100
 * Best for: Modern applications wanting latest Apache HTTP features
101
 * Features: HTTP/2, improved performance, modern API design
102
 * Note: Preview version with evolving API
103
 */
104
<dependency>
105
    <groupId>software.amazon.awssdk</groupId>
106
    <artifactId>apache5-client</artifactId>
107
    <version>${awsjavasdk.version}-PREVIEW</version>
108
</dependency>
109
```
110

111
### URL Connection Client
112

113
Java's built-in HTTP client implementation with minimal dependencies and JVM integration.
114

115
```xml { .api }
116
/**
117
 * Java URL Connection HTTP client implementation
118
 * Best for: Minimal dependencies, simple applications, restricted environments
119
 * Features: No external dependencies, JVM built-in, lightweight
120
 */
121
<dependency>
122
    <groupId>software.amazon.awssdk</groupId>
123
    <artifactId>url-connection-client</artifactId>
124
    <version>${awsjavasdk.version}</version>
125
</dependency>
126
```
127

128
**Usage Example:**
129

130
```xml
131
<dependencies>
132
    <!-- Service client -->
133
    <dependency>
134
        <groupId>software.amazon.awssdk</groupId>
135
        <artifactId>lambda</artifactId>
136
    </dependency>
137
    
138
    <!-- URL Connection HTTP client -->
139
    <dependency>
140
        <groupId>software.amazon.awssdk</groupId>
141
        <artifactId>url-connection-client</artifactId>
142
    </dependency>
143
</dependencies>
144
```
145

146
### AWS Common Runtime (CRT) Client
147

148
High-performance HTTP client implementation based on AWS Common Runtime for optimal performance.
149

150
```xml { .api }
151
/**
152
 * AWS Common Runtime HTTP client implementation
153
 * Best for: Maximum performance, native optimizations, latest AWS features
154
 * Features: Native performance, advanced AWS integrations, optimal throughput
155
 */
156
<dependency>
157
    <groupId>software.amazon.awssdk</groupId>
158
    <artifactId>aws-crt-client</artifactId>
159
    <version>${awsjavasdk.version}</version>
160
</dependency>
161
```
162

163
**Usage Example:**
164

165
```xml
166
<dependencies>
167
    <!-- Service client -->
168
    <dependency>
169
        <groupId>software.amazon.awssdk</groupId>
170
        <artifactId>s3</artifactId>
171
    </dependency>
172
    
173
    <!-- AWS CRT HTTP client -->
174
    <dependency>
175
        <groupId>software.amazon.awssdk</groupId>
176
        <artifactId>aws-crt-client</artifactId>
177
    </dependency>
178
</dependencies>
179
```
180

181
### HTTP Client SPI
182

183
Service Provider Interface for implementing custom HTTP client implementations.
184

185
```xml { .api }
186
/**
187
 * HTTP Client SPI - Service provider interface for custom HTTP implementations
188
 * Best for: Custom HTTP client implementations, SDK extensions
189
 * Features: Pluggable HTTP client architecture, extensibility interface
190
 */
191
<dependency>
192
    <groupId>software.amazon.awssdk</groupId>
193
    <artifactId>http-client-spi</artifactId>
194
    <version>${awsjavasdk.version}</version>
195
</dependency>
196
```
197

198
## HTTP Client Selection Guide
199

200
### Performance Characteristics
201

202
| Client | Type | Performance | Use Case |
203
|--------|------|-------------|----------|
204
| `netty-nio-client` | Async | High | High-throughput, non-blocking |
205
| `aws-crt-client` | Sync/Async | Highest | Maximum performance |
206
| `apache-client` | Sync | Good | Traditional applications |
207
| `apache5-client` | Sync | Good | Modern Apache features |
208
| `url-connection-client` | Sync | Basic | Minimal dependencies |
209
210
### Selection Criteria
211

212
**Choose Netty NIO Client when:**
213
- Building reactive or asynchronous applications
214
- Need high throughput and concurrent requests
215
- Using frameworks like Spring WebFlux or Vert.x
216
- Want non-blocking I/O operations
217

218
**Choose AWS CRT Client when:**
219
- Performance is critical
220
- Need latest AWS service optimizations
221
- Building high-scale applications
222
- Want native performance characteristics
223

224
**Choose Apache HTTP Client when:**
225
- Building traditional blocking applications
226
- Need extensive HTTP configuration options
227
- Require proxy support or custom SSL configurations
228
- Have existing Apache HttpClient expertise
229

230
**Choose URL Connection Client when:**
231
- Want minimal dependencies
232
- Building simple applications
233
- Working in restricted environments
234
- Don't need advanced HTTP features
235

236
## Usage Examples
237

238
**Multi-client setup for different services:**
239

240
```xml
241
<dependencies>
242
    <!-- S3 with high-performance CRT client -->
243
    <dependency>
244
        <groupId>software.amazon.awssdk</groupId>
245
        <artifactId>s3</artifactId>
246
    </dependency>
247
    <dependency>
248
        <groupId>software.amazon.awssdk</groupId>
249
        <artifactId>aws-crt-client</artifactId>
250
    </dependency>
251
    
252
    <!-- DynamoDB with async Netty client -->
253
    <dependency>
254
        <groupId>software.amazon.awssdk</groupId>
255
        <artifactId>dynamodb</artifactId>
256
    </dependency>
257
    <dependency>
258
        <groupId>software.amazon.awssdk</groupId>
259
        <artifactId>netty-nio-client</artifactId>
260
    </dependency>
261
    
262
    <!-- Lambda with minimal URL client -->
263
    <dependency>
264
        <groupId>software.amazon.awssdk</groupId>
265
        <artifactId>lambda</artifactId>
266
    </dependency>
267
    <dependency>
268
        <groupId>software.amazon.awssdk</groupId>
269
        <artifactId>url-connection-client</artifactId>
270
    </dependency>
271
</dependencies>
272
```
273

274
**Default client selection:**
275

276
If no HTTP client is explicitly added as a dependency, the SDK will automatically select a default client based on the classpath. The selection order is:
277

278
1. `netty-nio-client` (if available)
279
2. `apache-client` (if available)
280
3. `url-connection-client` (built-in fallback)
281

282
## Types
283

284
```xml { .api }
285
<!-- HTTP client dependency coordinates with version management -->
286
<dependency>
287
    <groupId>software.amazon.awssdk</groupId>
288
    <artifactId>netty-nio-client</artifactId>
289
    <version>${awsjavasdk.version}</version>
290
</dependency>
291

292
<dependency>
293
    <groupId>software.amazon.awssdk</groupId>
294
    <artifactId>apache-client</artifactId>
295
    <version>${awsjavasdk.version}</version>
296
</dependency>
297

298
<dependency>
299
    <groupId>software.amazon.awssdk</groupId>
300
    <artifactId>apache5-client</artifactId>
301
    <version>${awsjavasdk.version}-PREVIEW</version>
302
</dependency>
303

304
<dependency>
305
    <groupId>software.amazon.awssdk</groupId>
306
    <artifactId>url-connection-client</artifactId>
307
    <version>${awsjavasdk.version}</version>
308
</dependency>
309

310
<dependency>
311
    <groupId>software.amazon.awssdk</groupId>
312
    <artifactId>aws-crt-client</artifactId>
313
    <version>${awsjavasdk.version}</version>
314
</dependency>
315

316
<dependency>
317
    <groupId>software.amazon.awssdk</groupId>
318
    <artifactId>http-client-spi</artifactId>
319
    <version>${awsjavasdk.version}</version>
320
</dependency>
321
```