Skip to content

Commit b1e90eb

Browse files
pierwillrustagir
pierwill
and
rustagir
authored
DOCSP-30532 Stable API (#25)
Co-authored-by: pierwill <[email protected]> Co-authored-by: Rea Rustagi <[email protected]>
1 parent c9205ba commit b1e90eb

File tree

5 files changed

+191
-4
lines changed

5 files changed

+191
-4
lines changed

‎source/fundamentals.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@ Fundamentals
99
:maxdepth: 1
1010

1111
/fundamentals/connections
12+
/fundamentals/stable-api
1213
/fundamentals/crud
1314
/fundamentals/aggregation
1415
/fundamentals/tracing-logging
1516
/fundamentals/run-command
1617

1718
..
1819
Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
19-
/fundamentals/stable-api
2020
/fundamentals/context
2121
/fundamentals/auth
2222
/fundamentals/enterprise-auth
@@ -30,4 +30,4 @@ Fundamentals
3030
/fundamentals/encrypt-fields
3131
/fundamentals/geo
3232

33-
.. include:: /includes/fundamentals-sections.rst
33+
.. include:: /includes/fundamentals-sections.rst

‎source/fundamentals/stable-api.txt

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
.. _rust-stable-api:
2+
3+
==============
4+
{+stable-api+}
5+
==============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. important::
14+
15+
To use the {+stable-api+} feature, you must connect to a deployment running MongoDB Server version 5.0 or later.
16+
17+
You should only use the {+stable-api+} feature if all the MongoDB
18+
servers you are connecting to support this feature.
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to specify **{+stable-api+}**
24+
compatibility when connecting to a MongoDB instance or replica set.
25+
26+
The {+stable-api+} feature forces the server to run operations with
27+
behaviors that are compatible with the **API version** you specify. An API
28+
version defines the expected behavior of the operations it covers and
29+
the format of server responses. The operations and the server responses
30+
may differ depending on the API version you specify.
31+
32+
When you use the {+stable-api+} feature with an official MongoDB driver, you
33+
can update your driver or server without worrying about backward
34+
compatibility issues of the commands covered by the {+stable-api+}.
35+
36+
To learn more about the commands that the server covers, see
37+
:manual:`{+stable-api+} </reference/stable-api/>` in the Server manual.
38+
39+
Specify an API Version
40+
----------------------
41+
42+
To specify an API version, define a ``ServerApi`` struct and set the ``server_api`` field
43+
of your ``ClientOptions`` instance to this struct.
44+
The ``ServerApi`` struct contains your server API version and options.
45+
To learn more about the options, see the :ref:`Modify Behavior <rust-stable-api-options>` section of this guide.
46+
47+
After you specify an API version, the client runs operations that are compatible with the API version.
48+
49+
.. note::
50+
51+
The {+driver-long+} currently supports only {+stable-api+} version 1.
52+
53+
API Version Specification Example
54+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55+
56+
The following example sets the {+stable-api+} version when instantiating a ``Client``
57+
and connects to a server.
58+
59+
.. literalinclude:: /includes/fundamentals/code-snippets/stable-api.rs
60+
:language: rust
61+
:dedent:
62+
:start-after: start-stable-api
63+
:end-before: end-stable-api
64+
65+
.. _rust-stable-api-options:
66+
67+
Modify Behavior
68+
---------------
69+
70+
You can modify the behavior of the {+stable-api+} feature by setting fields in the ``ServerApi`` struct.
71+
72+
While you can set the fields in a ``ServerApi`` struct manually, you can use the builder design pattern to define the struct more efficiently.
73+
74+
.. list-table::
75+
:header-rows: 1
76+
:stub-columns: 1
77+
:class: compatibility-large
78+
79+
* - Field
80+
- Description
81+
82+
* - ``version``
83+
- | The {+stable-api+} version to use.
84+
| Specified with the ``ServerAPIVersion`` enum.
85+
86+
| Type: ``ServerAPIVersion``
87+
| Default: ``ServerAPIVersion1``
88+
89+
* - ``strict``
90+
- | Indicates whether the server should return errors for features that aren't part of the API version.
91+
|
92+
| Type: ``bool``
93+
| Default: ``false``
94+
95+
* - ``deprecation_errors``
96+
- | Indicates whether the server should return errors for deprecated features.
97+
|
98+
| Type: ``bool``
99+
| Default: ``false``
100+
101+
.. _rust-stable-api-options-example:
102+
103+
Stable API Options Example
104+
~~~~~~~~~~~~~~~~~~~~~~~~~~
105+
106+
This example enables the {+stable-api+} feature with the following specifications:
107+
108+
- Uses {+stable-api+} version 1
109+
- Returns errors for features that aren't part of version 1
110+
- Returns errors for deprecated features
111+
112+
.. literalinclude:: /includes/fundamentals/code-snippets/stable-api-behavior.rs
113+
:language: rust
114+
:dedent:
115+
:start-after: start-stable-api-behavior
116+
:end-before: end-stable-api-behavior
117+
118+
Additional Information
119+
----------------------
120+
121+
To learn more about connecting to your MongoDB instance or replica set,
122+
see the :ref:`rust-connect-to-mongodb`.
123+
124+
API Documentation
125+
~~~~~~~~~~~~~~~~~
126+
127+
To learn more about any of the methods or types discussed in this
128+
guide, see the following API Documentation:
129+
130+
- `Client <{+api+}/struct.Client.html>`__
131+
- `ClientOptions <{+api+}/options/struct.ClientOptions.html>`__
132+
- `ServerAPI <{+api+}/options/struct.ServerApi.html>`__
133+
- `ServerApiVersion <{+api+}/options/enum.ServerApiVersion.html>`__
134+
- `with_options() <{+api+}/options/struct.Client.html#method.with_options>`__
135+

‎source/includes/fundamentals-sections.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@ Learn how to perform the following tasks using the {+driver-short+} in the
22
Fundamentals section:
33

44
- :ref:`Connect to MongoDB <rust-connection>`
5+
- :ref:`Specify the {+stable-api+} Version <rust-stable-api>`
56
- :ref:`Read from and Write to MongoDB <rust-crud>`
67
- :ref:`Perform Aggregations <rust-aggregation>`
78
- :ref:`Record Driver Events <rust-tracing-logging>`
89
- :ref:`Run A Database Command <rust-run-command>`
910

1011
..
1112
- :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
12-
- :ref:`Specify the Stable API Version <rust-stable-api>`
1313
- :ref:`Authenticate to MongoDB <rust-authentication-mechanisms>`
1414
- :ref:`Connect with Enterprise Authentication Mechanisms <rust-enterprise-authentication-mechanisms>`
1515
- :ref:`Convert Data to and from BSON <rust-bson>`
@@ -19,4 +19,4 @@ Fundamentals section:
1919
- :ref:`Store and Retrieve Large Files by Using GridFS <rust-gridfs>`
2020
- :ref:`Use a Time Series Collection <rust-time-series>`
2121
- :ref:`Encrypt Fields <rust-fle>`
22-
- :ref:`Query and Write Geospatial Data <rust-geo>`
22+
- :ref:`Query and Write Geospatial Data <rust-geo>`

‎source/includes/fundamentals/code-snippets/stable-api-behavior.rs

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
use mongodb::{
2+
bson::doc,
3+
options::{ClientOptions, ServerApi, ServerApiVersion},
4+
sync::Client,
5+
};
6+
7+
fn main() -> mongodb::error::Result<()> {
8+
let uri = "<connection string>";
9+
// start-stable-api-behavior
10+
let mut client_options = ClientOptions::parse(uri)?;
11+
12+
let server_api = ServerApi::builder()
13+
.version(ServerApiVersion::V1)
14+
.strict(true)
15+
.deprecation_errors(true)
16+
.build();
17+
client_options.server_api = Some(server_api);
18+
19+
let client = Client::with_options(client_options)?;
20+
// end-stable-api-behavior
21+
22+
client
23+
.database("admin")
24+
.run_command(doc! { "ping": 1 }, None)?;
25+
println!("Pinged your deployment. You successfully connected to MongoDB!");
26+
27+
Ok(())
28+
}

‎source/includes/fundamentals/code-snippets/stable-api.rs

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
use mongodb::{
2+
bson::doc,
3+
options::{ClientOptions, ServerApi, ServerApiVersion},
4+
sync::Client,
5+
};
6+
7+
fn main() -> mongodb::error::Result<()> {
8+
let uri = "<connection string>";
9+
let mut client_options = ClientOptions::parse(uri)?;
10+
11+
// start-stable-api
12+
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
13+
client_options.server_api = Some(server_api);
14+
15+
let client = Client::with_options(client_options)?;
16+
// end-stable-api
17+
18+
client
19+
.database("admin")
20+
.run_command(doc! { "ping": 1 }, None)?;
21+
println!("Pinged your deployment. You successfully connected to MongoDB!");
22+
23+
Ok(())
24+
}

0 commit comments

Comments
 (0)