You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Contributing to the client is very much appreciated, no pull request (PR) is too big or too small!
4
+
We ask that _before_ opening a PR however, you check to see if there is an issue that discusses the change that you
5
+
wish to make. If there isn't, it's best to open a new issue first to discuss it, to save you time in future
6
+
and help us further ascertain the crux of the issue. If an issue already exists, please add to the discussion there.
7
+
8
+
Once an issue has been discussed and agreement that it should be acted upon, if you wish to work on a PR
9
+
to address it, please assign the issue to yourself, so that others know that it is being worked on.
10
+
11
+
## Sign the Contributor License Agreement
12
+
13
+
We do ask that you sign the [Contiributor License Agreement](https://www.elastic.co/contributor-agreement)
14
+
before we can accept pull requests from you.
15
+
16
+
## Development
17
+
18
+
The following information may help with contributing to this project. The workspace contains two packages:
19
+
20
+
### api_generator
21
+
22
+
A small executable to download REST API specs from GitHub and generate much of the client from the specs. Run with
23
+
24
+
```sh
25
+
cargo run -p api_generator
26
+
```
27
+
28
+
from the repository root directory, and follow the prompts. The minimum REST API spec version compatible with the
29
+
generator is `v7.4.0`.
30
+
31
+
The api_generator makes heavy use of the [`syn`](https://docs.rs/syn/1.0.5/syn/) and [`quote`](https://docs.rs/quote/1.0.2/quote/) crates to generate Rust code from the REST API specs.
32
+
The `quote!` macro is particularly useful as it accepts Rust code that can include placeholder tokens (prefixed with `#`)
33
+
that will be interpolated during expansion. Unlike procedural macros, the token stream returned by the `quote!` macro
34
+
can be `to_string()`'ed and written to disk, and this is used to create much of the client scaffolding.
35
+
36
+
### elasticsearch
37
+
38
+
The client package crate. The client exposes all Elasticsearch APIs as associated functions, either on
39
+
the root client, `Elasticsearch`, or on one of the _namespaced clients_, such as `Cat`, `Indices`, etc. The _namespaced clients_
40
+
are based on the grouping of APIs within the [Elasticsearch](https://github.com/elastic/elasticsearch/tree/master/rest-api-spec) and [X-Pack](https://github.com/elastic/elasticsearch/tree/master/x-pack/plugin/src/test/resources/rest-api-spec/api) REST API specs from which much of the client is generated.
41
+
All API functions are `async` only, and can be `await`ed.
42
+
43
+
### Design principles
44
+
45
+
1. Generate as much of the client as feasible from the REST API specs
46
+
47
+
The REST API specs contain information about
48
+
- the URL parts e.g. `{index}/{type}/_search` and variants
49
+
- accepted HTTP methods e.g. `GET`, `POST`
50
+
- the URL query string parameters
51
+
- whether the API accepts a body
52
+
53
+
2. Prefer generation methods that produce ASTs and token streams over strings.
54
+
The `quote` and `syn` crates help
55
+
56
+
3. Get it working, then refine/refactor
57
+
58
+
- Start simple and iterate
59
+
- Design of the API is conducive to ease of use
60
+
- Asynchronous only
61
+
- Control API invariants through arguments on API function. For example
An id must always be provided for a delete script API call, so the `delete_script()` function
70
+
must accept it as a value.
71
+
72
+
### Current development setup
73
+
74
+
Use Rust nightly for development for now:
75
+
76
+
```sh
77
+
> rustup show
78
+
...
79
+
80
+
active toolchain
81
+
----------------
82
+
83
+
nightly-x86_64-pc-windows-msvc (default)
84
+
rustc 1.41.0-nightly (a44774c3a 2019-11-25)
85
+
```
86
+
87
+
It is expected to move to rust stable once dependencies compile on stable.
88
+
89
+
### Coding style guide
90
+
91
+
The repository adheres to the styling enforced by `rustfmt`.
92
+
93
+
#### Formatting
94
+
95
+
Rust code can be formatted using [`rustfmt`](https://github.com/rust-lang/rustfmt). Follow the instructions to install.
96
+
97
+
To format all packages in a workspace, from the workspace root
98
+
99
+
```sh
100
+
cargo fmt
101
+
```
102
+
103
+
It is strongly recommended to run this before opening a PR.
104
+
105
+
#### Clippy
106
+
107
+
[Clippy](https://github.com/rust-lang/rust-clippy) is a bunch of lints to catch common mistakes and improve your Rust code! Follow the instructions to install.
108
+
109
+
Run clippy before opening a PR
110
+
111
+
```sh
112
+
cargo clippy
113
+
```
114
+
115
+
### Running MSVC debugger in VS Code
116
+
117
+
From [Bryce Van Dyk's blog post](https://www.brycevandyk.com/debug-rust-on-windows-with-visual-studio-code-and-the-msvc-debugger/),
118
+
if wishing to use the MSVC debugger with Rust in VS code, which may be preferred on Windows
119
+
120
+
1. Install [C/C++ VS Code extensions](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
121
+
122
+
2. Place the following in `.vscode/launch.json` in the project root
Official Rust Client for [Elasticsearch](https://github.com/elastic/elasticsearch).
2
2
3
-
An official Rust Client for Elasticsearch.
3
+
Full documentation is available at https://docs.rs/elasticsearch
4
4
5
5
The project is still very much a _work in progress_ and in an _alpha_ state;
6
6
input and contributions welcome!
@@ -31,34 +31,14 @@ functions on the client will be compatible.
31
31
Elasticsearch**. Major differences likely exist between major versions of Elasticsearch, particularly
32
32
around request and response object formats, but also around API urls and behaviour.
33
33
34
-
## Overview
34
+
## Getting started
35
35
36
-
The workspace contains two packages
37
-
38
-
### api_generator
39
-
40
-
A small executable to download REST API specs from GitHub and generate much of the client from the specs. Run with
41
-
42
-
```sh
43
-
cargo run -p api_generator
44
-
```
45
-
46
-
from the repository root directory, and follow the prompts. The minimum REST API spec version compatible with the
47
-
generator is `v7.4.0`.
48
-
49
-
The api_generator makes heavy use of the [`syn`](https://docs.rs/syn/1.0.5/syn/) and [`quote`](https://docs.rs/quote/1.0.2/quote/) crates to generate Rust code from the REST API specs.
50
-
The `quote!` macro is particularly useful as it accepts Rust code that can include placeholder tokens (prefixed with `#`)
51
-
that will be interpolated during expansion. Unlike procedural macros, the token stream returned by the `quote!` macro
52
-
can be `to_string()`'ed and written to disk, and this is used to create much of the client scaffolding.
53
-
54
-
### elasticsearch
55
-
56
-
The client package crate. The client exposes all Elasticsearch APIs as associated functions, either on
36
+
The client exposes all Elasticsearch APIs as associated functions, either on
57
37
the root client, `Elasticsearch`, or on one of the _namespaced clients_, such as `Cat`, `Indices`, etc. The _namespaced clients_
58
38
are based on the grouping of APIs within the [Elasticsearch](https://github.com/elastic/elasticsearch/tree/master/rest-api-spec) and [X-Pack](https://github.com/elastic/elasticsearch/tree/master/x-pack/plugin/src/test/resources/rest-api-spec/api) REST API specs from which much of the client is generated.
59
39
All API functions are `async` only, and can be `await`ed.
60
40
61
-
####Installing
41
+
### Installing
62
42
63
43
Add `elasticsearch` crate and version to Cargo.toml. Choose the version
64
44
that is compatible with the version of Elasticsearch you're using
@@ -75,7 +55,7 @@ serde = "~1"
75
55
serde_json = "~1"
76
56
```
77
57
78
-
####Create a client
58
+
### Create a client
79
59
80
60
Build a transport to make API requests to Elasticsearch using the `TransportBuilder`,
81
61
which allows setting of proxies and authentication schemes
An id must always be provided for a delete script API call, so the `delete_script()` function
221
-
must accept it as a value.
222
-
223
-
## Contributing
224
-
225
-
Contributing to the client is very much appreciated, no pull request (PR) is too big or too small!
226
-
We ask that _before_ opening a PR however, you check to see if there is an issue that discusses the change that you
227
-
wish to make. If there isn't, it's best to open a new issue first to discuss it, to save you time in future
228
-
and help us further ascertain the crux of the issue. If an issue already exists, please add to the discussion there.
229
-
230
-
Once an issue has been discussed and agreement that it should be acted upon, if you wish to work on a PR
231
-
to address it, please assign the issue to yourself, so that others know that it is being worked on.
232
-
233
-
### Sign the Contributor License Agreement
234
-
235
-
We do ask that you sign the [Contiributor License Agreement](https://www.elastic.co/contributor-agreement)
236
-
before we can accept pull requests from you.
237
-
238
-
### Current Setup
239
-
240
-
Use Rust nightly for development for now:
241
-
242
-
```sh
243
-
> rustup show
244
-
...
245
-
246
-
active toolchain
247
-
----------------
248
-
249
-
nightly-x86_64-pc-windows-msvc (default)
250
-
rustc 1.41.0-nightly (a44774c3a 2019-11-25)
251
-
```
172
+
API call to an endpoint not represented as an API function, for example, experimental
173
+
and beta APIs
252
174
253
-
It is expected to move to rust stable once dependencies compile on stable.
254
-
255
-
### Coding styleguide
256
-
257
-
The repository adheres to the styling enforced by `rustfmt`.
258
-
259
-
#### Formatting
260
-
261
-
Rust code can be formatted using [`rustfmt`](https://github.com/rust-lang/rustfmt). Follow the instructions to install.
262
-
263
-
To format all packages in a workspace, from the workspace root
264
-
265
-
```sh
266
-
cargo fmt
267
-
```
268
-
269
-
It is strongly recommended to run this before opening a PR.
270
-
271
-
#### Clippy
272
-
273
-
[Clippy](https://github.com/rust-lang/rust-clippy) is a bunch of lints to catch common mistakes and improve your Rust code! Follow the instructions to install.
274
-
275
-
Run clippy before opening a PR
175
+
```rust,no_run
176
+
use elasticsearch::{http::Method, Elasticsearch, Error, SearchParts};
177
+
use http::HeaderMap;
178
+
use serde_json::{json, Value};
179
+
use url::Url;
276
180
277
-
```sh
278
-
cargo clippy
181
+
async fn run() -> Result<(), Error> {
182
+
let client = Elasticsearch::default();
183
+
let body = b"{\"query\":{\"match_all\":{}}}";
184
+
let response = client
185
+
.send(Method::Post,
186
+
SearchParts::Index(&["tweets"]).url().as_ref(),
187
+
HeaderMap::new(),
188
+
Option::<&Value>::None,
189
+
Some(body.as_ref())
190
+
)
191
+
.await?;
192
+
Ok(())
193
+
}
279
194
```
280
195
281
-
## Development
282
-
283
-
### Running MSVC debugger in VS Code
284
-
285
-
From [Bryce Van Dyk's blog post](https://www.brycevandyk.com/debug-rust-on-windows-with-visual-studio-code-and-the-msvc-debugger/),
286
-
if wishing to use the MSVC debugger with Rust in VS code, which may be preferred on Windows
287
-
288
-
1. Install [C/C++ VS Code extensions](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
289
-
290
-
2. Place the following in `.vscode/launch.json` in the project root
0 commit comments