Skip to content

Commit 981dfbb

Browse files
mcmorisimcmorisi
authored
DOCSP-42298: Stable API (#76)
1 parent 7836171 commit 981dfbb

File tree

5 files changed

+175
-4
lines changed

5 files changed

+175
-4
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,5 @@ java-rs = "Java Reactive Streams"
2727
string-data-type = "``String``"
2828
bool = "``boolean``"
2929
pr = "Project Reactor"
30-
mdb-server = "MongoDB Server"
30+
mdb-server = "MongoDB Server"
31+
stable-api = "Stable API"

‎source/connect-to-mongo/choose-connection-target.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,13 @@ Then, pass your connection string to the ``create()`` method constructing a ``Mo
4040
Follow the :atlas:`Atlas driver connection guide </driver-connection>`
4141
to retrieve your connection string.
4242

43-
When you connect to Atlas, we recommend using the Stable API client option to avoid
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
4444
breaking changes when Atlas upgrades to a new version of MongoDB Server.
45-
To learn more about the Stable API feature, see :manual:`Stable API
45+
To learn more about the {+stable-api+} feature, see :manual:`Stable API
4646
</reference/stable-api>` in the MongoDB Server manual.
4747

4848
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
49-
code uses the ``serverApi`` option to specify a Stable API version.
49+
code uses the ``serverApi`` option to specify a {+stable-api+} version.
5050

5151
.. include:: /includes/connect/connect-reactor.rst
5252

‎source/connect-to-mongo/stable-api.txt

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _java-rs-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+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: compatible, backwards, upgrade
19+
20+
.. note::
21+
22+
The {+stable-api+} feature requires {+mdb-server+} 5.0 or later.
23+
24+
Overview
25+
--------
26+
27+
In this guide, you can learn how to specify **{+stable-api+}** compatibility when
28+
connecting to a MongoDB deployment.
29+
30+
The {+stable-api+} feature forces the server to run operations with behaviors compatible
31+
with the API version you specify. Using the {+stable-api+} ensures consistent responses
32+
from the server and provides long-term API stability for your application.
33+
34+
The following sections describe how you can enable and customize {+stable-api+} for
35+
your MongoDB client. For more information about the {+stable-api+}, including a list of
36+
the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
37+
{+mdb-server+} manual.
38+
39+
Enable the {+stable-api+}
40+
-------------------------
41+
42+
To enable the {+stable-api+}, perform the following steps:
43+
44+
1. Construct a ``ServerApi`` object and specify a {+stable-api+} version. You must use
45+
a {+stable-api+} version defined in the ``ServerApiVersion`` enum.
46+
#. Construct a ``MongoClientSettings`` object using the ``MongoClientSettings.Builder`` class.
47+
#. Instantiate a ``MongoClient`` using the ``MongoClients.create()`` method and
48+
pass your ``MongoClientSettings`` instance as a parameter.
49+
50+
The following code example shows how to specify {+stable-api+} version 1:
51+
52+
.. literalinclude:: /includes/connect/stable-api.java
53+
:start-after: start-enable-stable-api
54+
:end-before: end-enable-stable-api
55+
:language: java
56+
:copyable:
57+
:dedent:
58+
59+
Once you create a ``MongoClient`` instance with the {+stable-api+}, all commands you
60+
run with the client use the specified {+stable-api+} configuration. If you must run
61+
commands using alternative configurations, create a new ``MongoClient``.
62+
63+
.. _java-rs-stable-api-options:
64+
65+
Configure the {+stable-api+}
66+
----------------------------
67+
68+
The following table describes chainable methods of the ``ServerApi.Builder`` class that
69+
you can use to customize the behavior of the {+stable-api+}.
70+
71+
.. list-table::
72+
:header-rows: 1
73+
:stub-columns: 1
74+
:widths: 25,75
75+
76+
* - Option Name
77+
- Description
78+
79+
* - ``strict()``
80+
- | **Optional**. When ``true``, if you call a command that isn't part of
81+
the declared API version, the driver raises an exception.
82+
|
83+
| Default: **false**
84+
85+
* - ``deprecationErrors()``
86+
- | **Optional**. When ``true``, if you call a command that is deprecated in the
87+
declared API version, the driver raises an exception.
88+
|
89+
| Default: **false**
90+
91+
The following code example shows how you can configure an instance of ``ServerApi``
92+
by chaining methods on the ``ServerApi.Builder``:
93+
94+
.. literalinclude:: /includes/connect/stable-api.java
95+
:start-after: start-stable-api-options
96+
:end-before: end-stable-api-options
97+
:language: java
98+
:copyable:
99+
:dedent:
100+
101+
Troubleshooting
102+
---------------
103+
104+
Unrecognized field 'apiVersion' on server
105+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106+
107+
The {+driver-short+} raises this exception if you specify an API version and connect to a
108+
MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a
109+
deployment running {+mdb-server+} v5.0 or later.
110+
111+
Provided apiStrict:true, but the command <operation> is not in API Version
112+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113+
114+
The {+driver-short+} raises this exception if your ``MongoClient`` runs an operation that
115+
isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative
116+
operation supported by the specified {+stable-api+} version, or set the ``strict``
117+
option to ``False`` when constructing your ``ServerApi`` object.
118+
119+
API Documentation
120+
-----------------
121+
122+
For more information about using the {+stable-api+} with the {+driver-short+}, see the
123+
following API documentation:
124+
125+
- `ServerApi <{+api+}/mongodb-driver-core/com/mongodb/ServerApi.html>`__
126+
- `ServerApi.Builder <{+api+}/mongodb-driver-core/com/mongodb/ServerApi.Builder.html>`__
127+
- `ServerApiVersion <{+api+}/mongodb-driver-core/com/mongodb/ServerApiVersion.html>`__
128+
- `ServerAddress <{+api+}/mongodb-driver-core/com/mongodb/ServerAddress.html>`__
129+
- `MongoClientSettings <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__
130+
- `MongoClientSettings.Builder <{+api+}/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
131+
- `MongoClients <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClients.html>`__

‎source/connect.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Connect to MongoDB
2727
/connect-to-mongo/connection-options/
2828
/connect-to-mongo/tls/
2929
/connect-to-mongo/compression/
30+
/connect-to-mongo/stable-api/
3031

3132
Overview
3233
--------

‎source/includes/connect/stable-api.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
package org.example;
2+
3+
import com.mongodb.ConnectionString;
4+
import com.mongodb.MongoClientSettings;
5+
import com.mongodb.ServerApi;
6+
import com.mongodb.ServerApiVersion;
7+
8+
import com.mongodb.reactivestreams.client.*;
9+
10+
public class Main {
11+
public static void main(String[] args) {
12+
// start-enable-stable-api
13+
ServerApi serverApi = ServerApi.builder()
14+
.version(ServerApiVersion.V1)
15+
.build();
16+
17+
// Replace the placeholder with your Atlas connection string
18+
String uri = "<connection string URI>";
19+
20+
MongoClientSettings settings = MongoClientSettings.builder()
21+
.applyConnectionString(new ConnectionString(uri))
22+
.serverApi(serverApi)
23+
.build();
24+
25+
try (MongoClient mongoClient = MongoClients.create(settings)) {
26+
// Perform client operations here
27+
}
28+
// end-enable-stable-api
29+
30+
// start-stable-api-options
31+
ServerApi serverApi = ServerApi.builder()
32+
.version(ServerApiVersion.V1)
33+
.strict(true)
34+
.deprecationErrors(true)
35+
.build();
36+
// end-stable-api-options
37+
}
38+
}

0 commit comments

Comments
 (0)