0
# Client APIs
1

2
Core client interfaces and transport mechanisms for connecting to and communicating with OpenSearch clusters. The client layer provides both high-level typed interfaces and low-level REST HTTP access.
3

4
## Capabilities
5

6
### Primary Client Interface
7

8
The main `Client` interface provides a unified API for all OpenSearch operations with both synchronous and asynchronous execution patterns.
9

10
```java { .api }
11
/**
12
 * Main client interface for all OpenSearch operations.
13
 * Provides typed access to cluster operations with async support.
14
 */
15
interface Client extends Closeable {
16
    /**
17
     * Execute an action with typed request and response handling
18
     * @param action The action type to execute
19
     * @param request The request parameters
20
     * @param listener Callback for async response handling
21
     */
22
    <Request extends ActionRequest, Response extends ActionResponse>
23
    void execute(ActionType<Response> action, Request request, ActionListener<Response> listener);
24
    
25
    /**
26
     * Execute an action synchronously
27
     * @param action The action type to execute  
28
     * @param request The request parameters
29
     * @return The response object
30
     */
31
    <Request extends ActionRequest, Response extends ActionResponse>
32
    Response execute(ActionType<Response> action, Request request);
33
    
34
    /**
35
     * Get administrative client for cluster and index management
36
     */
37
    AdminClient admin();
38
    
39
    /**
40
     * Get client settings configuration
41
     */
42
    Settings settings();
43
    
44
    /**
45
     * Close client and release resources
46
     */
47
    void close();
48
}
49
```
50

51
**Usage Example:**
52

53
```java
54
import org.opensearch.client.Client;
55
import org.opensearch.action.search.SearchRequest;
56
import org.opensearch.action.search.SearchResponse;
57
import org.opensearch.action.ActionListener;
58

59
// Synchronous execution
60
SearchRequest request = new SearchRequest("products");
61
SearchResponse response = client.execute(SearchAction.INSTANCE, request);
62

63
// Asynchronous execution
64
client.execute(SearchAction.INSTANCE, request, new ActionListener<SearchResponse>() {
65
    @Override
66
    public void onResponse(SearchResponse response) {
67
        System.out.println("Search completed: " + response.getHits().getTotalHits().value);
68
    }
69
    
70
    @Override
71
    public void onFailure(Exception e) {
72
        System.err.println("Search failed: " + e.getMessage());
73
    }
74
});
75
```
76

77
### Administrative Clients
78

79
Administrative operations are organized into separate client interfaces for cluster and index management.
80

81
```java { .api }
82
/**
83
 * Administrative operations client providing access to cluster and index management
84
 */
85
interface AdminClient {
86
    /**
87
     * Get cluster administration client
88
     */
89
    ClusterAdminClient cluster();
90
    
91
    /**
92
     * Get index administration client  
93
     */
94
    IndicesAdminClient indices();
95
}
96

97
/**
98
 * Cluster-level administrative operations
99
 */
100
interface ClusterAdminClient {
101
    /**
102
     * Execute cluster health check
103
     */
104
    void health(ClusterHealthRequest request, ActionListener<ClusterHealthResponse> listener);
105
    
106
    /**
107
     * Get cluster state information
108
     */
109
    void state(ClusterStateRequest request, ActionListener<ClusterStateResponse> listener);
110
    
111
    /**
112
     * Get cluster statistics
113
     */
114
    void stats(ClusterStatsRequest request, ActionListener<ClusterStatsResponse> listener);
115
    
116
    /**
117
     * Update cluster settings
118
     */
119
    void updateSettings(ClusterUpdateSettingsRequest request, 
120
        ActionListener<ClusterUpdateSettingsResponse> listener);
121
    
122
    /**
123
     * Get node information
124
     */
125
    void nodesInfo(NodesInfoRequest request, ActionListener<NodesInfoResponse> listener);
126
    
127
    /**
128
     * Get node statistics
129
     */
130
    void nodesStats(NodesStatsRequest request, ActionListener<NodesStatsResponse> listener);
131
}
132

133
/**
134
 * Index-level administrative operations
135
 */
136
interface IndicesAdminClient {
137
    /**
138
     * Create an index
139
     */
140
    void create(CreateIndexRequest request, ActionListener<CreateIndexResponse> listener);
141
    
142
    /**
143
     * Delete an index
144
     */
145
    void delete(DeleteIndexRequest request, ActionListener<AcknowledgedResponse> listener);
146
    
147
    /**
148
     * Get index information
149
     */
150
    void get(GetIndexRequest request, ActionListener<GetIndexResponse> listener);
151
    
152
    /**
153
     * Put index mapping
154
     */
155
    void putMapping(PutMappingRequest request, ActionListener<AcknowledgedResponse> listener);
156
    
157
    /**
158
     * Get index mappings
159
     */
160
    void getMappings(GetMappingsRequest request, ActionListener<GetMappingsResponse> listener);
161
    
162
    /**
163
     * Update index settings
164
     */
165
    void updateSettings(UpdateSettingsRequest request, ActionListener<AcknowledgedResponse> listener);
166
    
167
    /**
168
     * Refresh index
169
     */
170
    void refresh(RefreshRequest request, ActionListener<RefreshResponse> listener);
171
}
172
```
173

174
### Node Client
175

176
Direct client implementation for in-process access to OpenSearch nodes.
177

178
```java { .api }
179
/**
180
 * Node-specific client implementation providing direct access to local node
181
 */
182
class NodeClient extends AbstractClient {
183
    /**
184
     * Create node client with specified node reference
185
     * @param node The node instance to connect to
186
     */
187
    NodeClient(Node node);
188
    
189
    /**
190
     * Get the local node reference
191
     */
192
    Node getLocalNode();
193
    
194
    /**
195
     * Get node ID
196
     */
197
    String getLocalNodeId();
198
}
199
```
200

201
### REST Client APIs
202

203
Low-level HTTP REST client for direct API access and custom implementations.
204

205
```java { .api }
206
/**
207
 * Low-level REST client for HTTP operations against OpenSearch cluster
208
 */
209
class RestClient implements Closeable {
210
    /**
211
     * Create REST client builder with host configuration
212
     * @param hosts Array of cluster hosts to connect to
213
     */
214
    static RestClientBuilder builder(HttpHost... hosts);
215
    
216
    /**
217
     * Perform synchronous HTTP request
218
     * @param request HTTP request to execute
219
     * @return HTTP response
220
     * @throws IOException if request fails
221
     */
222
    Response performRequest(Request request) throws IOException;
223
    
224
    /**
225
     * Perform asynchronous HTTP request  
226
     * @param request HTTP request to execute
227
     * @param responseListener Callback for response handling
228
     */
229
    void performRequestAsync(Request request, ResponseListener responseListener);
230
    
231
    /**
232
     * Close client and release resources
233
     */
234
    void close() throws IOException;
235
}
236

237
/**
238
 * Builder for REST client configuration
239
 */
240
class RestClientBuilder {
241
    /**
242
     * Set request configuration options
243
     */
244
    RestClientBuilder setRequestConfigCallback(RequestConfigCallback requestConfigCallback);
245
    
246
    /**
247
     * Set HTTP client configuration
248
     */
249
    RestClientBuilder setHttpClientConfigCallback(HttpClientConfigCallback httpClientConfigCallback);
250
    
251
    /**
252
     * Set default headers for all requests
253
     */
254
    RestClientBuilder setDefaultHeaders(Header[] defaultHeaders);
255
    
256
    /**
257
     * Set node selector for request routing
258
     */
259
    RestClientBuilder setNodeSelector(NodeSelector nodeSelector);
260
    
261
    /**
262
     * Build the REST client instance
263
     */
264
    RestClient build();
265
}
266
```
267

268
### HTTP Request and Response
269

270
Classes for constructing and handling HTTP operations.
271

272
```java { .api }
273
/**
274
 * HTTP request representation for REST client operations
275
 */
276
class Request {
277
    /**
278
     * Create HTTP request
279
     * @param method HTTP method (GET, POST, PUT, DELETE)
280
     * @param endpoint API endpoint path
281
     */
282
    Request(String method, String endpoint);
283
    
284
    /**
285
     * Add request parameter
286
     */
287
    void addParameter(String name, String value);
288
    
289
    /**
290
     * Set request entity body
291
     */
292
    void setEntity(HttpEntity entity);
293
    
294
    /**
295
     * Set JSON entity from string
296
     */
297
    void setJsonEntity(String json);
298
    
299
    /**
300
     * Get HTTP method
301
     */
302
    String getMethod();
303
    
304
    /**
305
     * Get endpoint path
306
     */
307
    String getEndpoint();
308
}
309

310
/**
311
 * HTTP response representation
312
 */
313
class Response {
314
    /**
315
     * Get response status line
316
     */
317
    StatusLine getStatusLine();
318
    
319
    /**
320
     * Get response entity
321
     */
322
    HttpEntity getEntity();
323
    
324
    /**
325
     * Get response headers
326
     */
327
    Header[] getHeaders();
328
    
329
    /**
330
     * Get response host information
331
     */
332
    HttpHost getHost();
333
}
334

335
/**
336
 * Callback interface for asynchronous response handling
337
 */
338
interface ResponseListener {
339
    /**
340
     * Called on successful response
341
     */
342
    void onSuccess(Response response);
343
    
344
    /**
345
     * Called on request failure
346
     */
347
    void onFailure(Exception exception);
348
}
349
```
350

351
### Request Configuration
352

353
Configuration classes for customizing client behavior.
354

355
```java { .api }
356
/**
357
 * Request configuration options
358
 */
359
class RequestOptions {
360
    /**
361
     * Default request options
362
     */
363
    static final RequestOptions DEFAULT;
364
    
365
    /**
366
     * Create request options builder
367
     */
368
    static Builder toBuilder();
369
    
370
    /**
371
     * Get request headers
372
     */
373
    List<Header> getHeaders();
374
    
375
    /**
376
     * Get request configuration
377
     */
378
    RequestConfig getRequestConfig();
379
    
380
    /**
381
     * Builder for request options
382
     */
383
    static class Builder {
384
        /**
385
         * Add request header
386
         */
387
        Builder addHeader(String name, String value);
388
        
389
        /**
390
         * Set request configuration
391
         */
392
        Builder setRequestConfig(RequestConfig requestConfig);
393
        
394
        /**
395
         * Build request options
396
         */
397
        RequestOptions build();
398
    }
399
}
400
```
401

402
## Usage Examples
403

404
### Basic REST Client Setup
405

406
```java
407
import org.opensearch.client.RestClient;
408
import org.opensearch.client.RestClientBuilder;
409
import org.opensearch.client.Request;
410
import org.opensearch.client.Response;
411
import org.apache.http.HttpHost;
412
import org.apache.http.auth.AuthScope;
413
import org.apache.http.auth.UsernamePasswordCredentials;
414
import org.apache.http.client.CredentialsProvider;
415
import org.apache.http.impl.client.BasicCredentialsProvider;
416

417
// Basic client setup
418
RestClient client = RestClient.builder(
419
    new HttpHost("localhost", 9200, "http"),
420
    new HttpHost("localhost", 9201, "http")
421
).build();
422

423
// With authentication
424
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
425
credentialsProvider.setCredentials(AuthScope.ANY, 
426
    new UsernamePasswordCredentials("username", "password"));
427

428
RestClient secureClient = RestClient.builder(
429
    new HttpHost("localhost", 9200, "https")
430
).setHttpClientConfigCallback(httpClientBuilder -> 
431
    httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider)
432
).build();
433
```
434

435
### Administrative Operations
436

437
```java
438
import org.opensearch.action.admin.cluster.health.ClusterHealthRequest;
439
import org.opensearch.action.admin.cluster.health.ClusterHealthResponse;
440
import org.opensearch.cluster.health.ClusterHealthStatus;
441

442
// Check cluster health
443
ClusterHealthRequest healthRequest = new ClusterHealthRequest();
444
healthRequest.timeout("10s");
445
healthRequest.waitForStatus(ClusterHealthStatus.YELLOW);
446

447
client.admin().cluster().health(healthRequest, new ActionListener<ClusterHealthResponse>() {
448
    @Override
449
    public void onResponse(ClusterHealthResponse response) {
450
        System.out.println("Cluster status: " + response.getStatus());
451
        System.out.println("Number of nodes: " + response.getNumberOfNodes());
452
    }
453
    
454
    @Override
455
    public void onFailure(Exception e) {
456
        System.err.println("Health check failed: " + e.getMessage());
457
    }
458
});
459
```
460

461
### Error Handling
462

463
```java
464
import org.opensearch.OpenSearchException;
465
import org.opensearch.OpenSearchTimeoutException;
466
import org.opensearch.rest.RestStatus;
467

468
try {
469
    SearchResponse response = client.execute(SearchAction.INSTANCE, searchRequest);
470
    // Process response
471
} catch (OpenSearchTimeoutException e) {
472
    System.err.println("Request timed out: " + e.getMessage());
473
} catch (OpenSearchException e) {
474
    System.err.println("OpenSearch error: " + e.status() + " - " + e.getMessage());
475
    if (e.status() == RestStatus.NOT_FOUND) {
476
        // Handle missing index/document
477
    }
478
} catch (Exception e) {
479
    System.err.println("General error: " + e.getMessage());
480
}
481
```
482

483
## Types
484

485
```java { .api }
486
/**
487
 * Callback interface for asynchronous action execution
488
 */
489
interface ActionListener<Response> {
490
    /**
491
     * Called when action completes successfully
492
     * @param response The action response
493
     */
494
    void onResponse(Response response);
495
    
496
    /**
497
     * Called when action fails  
498
     * @param e The failure exception
499
     */
500
    void onFailure(Exception e);
501
}
502

503
/**
504
 * Base class for all action requests
505
 */
506
abstract class ActionRequest implements Streamable, Validatable {
507
    /**
508
     * Validate request parameters
509
     * @return Validation result
510
     */
511
    ActionRequestValidationException validate();
512
}
513

514
/**
515
 * Base class for all action responses  
516
 */
517
abstract class ActionResponse implements Streamable {
518
    // Response base functionality
519
}
520

521
/**
522
 * Configuration callback for HTTP client setup
523
 */
524
interface HttpClientConfigCallback {
525
    /**
526
     * Customize HTTP client builder
527
     */
528
    HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder);
529
}
530

531
/**
532
 * Configuration callback for request setup
533
 */
534
interface RequestConfigCallback {
535
    /**
536
     * Customize request configuration
537
     */
538
    RequestConfig.Builder customizeRequestConfig(RequestConfig.Builder requestConfigBuilder);
539
}
540
```