Skip to content

Commit c0d0d77

Browse files
author
Chris Cho
authored
DOCSP-15781: Versioned API (#87)
* DOCSP-15781: Versioned API page
1 parent f4666e9 commit c0d0d77

File tree

3 files changed

+178
-0
lines changed

3 files changed

+178
-0
lines changed

‎source/fundamentals.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Fundamentals
99
:maxdepth: 1
1010

1111
/fundamentals/connection
12+
/fundamentals/versioned-api
1213
/fundamentals/auth
1314
/fundamentals/enterprise-auth
1415
/fundamentals/databases-collections

‎source/fundamentals/versioned-api.txt

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
=============
2+
Versioned API
3+
=============
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. note::
14+
15+
The Versioned API feature requires MongoDB Server 5.0 or later.
16+
17+
You should only use the Versioned API feature if all the MongoDB
18+
servers you are connecting to support this feature.
19+
20+
This guide shows you how to specify the **Versioned API** when connecting to
21+
a MongoDB instance or replica set. You can use the Versioned API feature to
22+
force the server to run operations with behavior compatible with the
23+
specified **API version**. An API version defines the expected behavior of the
24+
operations it covers and the format of server responses. If you change to
25+
a different API version, the operations are not guaranteed to be
26+
compatible and the server responses are not guaranteed to be similar.
27+
28+
When you use the Versioned API feature with an official MongoDB driver, you
29+
can update your driver or server without worrying about backward compatibility
30+
issues of the commands covered by the Versioned API.
31+
32+
See the server manual page on `Versioned API <https://docs.mongodb.com/v5.0/reference/versioned-api/>`__
33+
for more information including a list of commands it covers.
34+
35+
The following sections describe how you can enable Versioned API for
36+
your MongoDB client and the options that you can specify.
37+
38+
Enable Versioned API on a MongoDB Client
39+
----------------------------------------
40+
41+
To enable the Versioned API, you must specify an API version in the settings
42+
of your MongoDB client. Once you instantiate a ``MongoClient`` instance with
43+
a specified Versioned API, all commands you run with that client use that
44+
version of the Versioned API.
45+
46+
.. tip::
47+
48+
If you need to run commands using a more than one version of the Versioned
49+
API, instantiate a separate client with that version.
50+
51+
If you need to run commands not covered by the Versioned API, make sure the
52+
"strict" option is disabled. See the section on
53+
:ref:`Versioned API Options <versioned-api-options>` for more information.
54+
55+
The example below shows how you can instantiate a ``MongoClient`` that
56+
sets the Versioned API version and connects to a server by performing the
57+
following operations:
58+
59+
- Construct a ``ServerApi`` instance using the ``ServerApi.Builder``
60+
helper class.
61+
- Specify a Versioned API version using a constant from the
62+
``ServerApiVersion`` class.
63+
- Construct a ``MongoClientSettings`` instance using the
64+
``MongoClientSettings.Builder`` class.
65+
- Specify a server to connect to using a ``ServerAddress`` instance.
66+
- Instantiate a ``MongoClient`` using the ``MongoClients.create()`` method
67+
and pass your ``MongoClientSettings`` instance as a parameter.
68+
69+
.. literalinclude:: /includes/fundamentals/code-snippets/VersionedApiExample.java
70+
:start-after: start serverAPIVersion
71+
:end-before: end serverAPIVersion
72+
:language: java
73+
:dedent:
74+
75+
.. warning::
76+
77+
If you specify an API version and connect to a MongoDB server that does
78+
not support Versioned API, your application may raise an exception when
79+
executing a command on your MongoDB server. If you use a ``MongoClient``
80+
that specifies the API version to query a server that does not support it,
81+
your query could fail with an exception message that includes the
82+
following text:
83+
84+
.. code-block:: none
85+
:copyable: false
86+
87+
'Unrecognized field 'apiVersion' on server...
88+
89+
For more information on the methods and classes referenced in this
90+
section, see the following API documentation:
91+
92+
- :java-docs:`ServerApi <apidocs/mongodb-driver-core/com/mongodb/ServerApi.html>`
93+
- :java-docs:`ServerApi.Builder <apidocs/mongodb-driver-core/com/mongodb/ServerApi.Builder.html>`
94+
- :java-docs:`ServerApiVersion </apidocs/mongodb-driver-core/com/mongodb/ServerApiVersion.html>`
95+
- :java-docs:`ServerAddress <apidocs/mongodb-driver-core/com/mongodb/ServerAddress.html>`
96+
- :java-docs:`MongoClientSettings <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`
97+
- :java-docs:`MongoClientSettings.Builder <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`
98+
- :java-docs:`MongoClients.create() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html#create(com.mongodb.MongoClientSettings)>`
99+
- :java-docs:`MongoClient <apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`
100+
101+
.. _versioned-api-options:
102+
103+
Versioned API Options
104+
---------------------
105+
106+
You can enable or disable optional behavior related to Versioned API as
107+
described in the following table.
108+
109+
.. list-table::
110+
:header-rows: 1
111+
:stub-columns: 1
112+
:widths: 25,75
113+
114+
* - Option Name
115+
- Description
116+
117+
* - Strict
118+
- | **Optional**. When set, if you call a command that is not part of declared API version, the driver raises an exception.
119+
|
120+
| Default: **false**
121+
| For more information, see the :java-docs:`strict() <apidocs/mongodb-driver-core/com/mongodb/ServerApi.Builder.html#strict(boolean)>` API documentation.
122+
123+
* - DeprecationErrors
124+
- | **Optional**. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception.
125+
|
126+
| Default: **false**
127+
| For more information, see the :java-docs:`deprecationErrors() <apidocs/mongodb-driver-core/com/mongodb/ServerApi.Builder.html#>` API documentation.
128+
129+
130+
The following example shows how you can set the two options on an instance
131+
of ``ServerApi`` by chaining methods on the ``ServerApi.Builder``:
132+
133+
.. literalinclude:: /includes/fundamentals/code-snippets/VersionedApiExample.java
134+
:start-after: start apiVersionOptions
135+
:end-before: end apiVersionOptions
136+
:language: java
137+
:dedent:
138+

‎source/includes/fundamentals/code-snippets/VersionedApiExample.java

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
package fundamentals;
2+
3+
import com.mongodb.ConnectionString;
4+
import com.mongodb.MongoClientSettings;
5+
import com.mongodb.ServerApi;
6+
import com.mongodb.ServerApiVersion;
7+
import com.mongodb.client.MongoClient;
8+
import com.mongodb.client.MongoClients;
9+
10+
public class VersionedApiExample {
11+
private static void setApiVersionOptions(String uri) {
12+
// start apiVersionOptions
13+
ServerApi serverApi = ServerApi.builder()
14+
.version(ServerApiVersion.V1)
15+
.strict(true)
16+
.deprecationErrors(true)
17+
.build();
18+
// end apiVersionOptions
19+
}
20+
21+
public static void main(String[] args) {
22+
// start serverAPIVersion
23+
ServerApi serverApi = ServerApi.builder()
24+
.version(ServerApiVersion.V1)
25+
.build();
26+
27+
// Replace the uri string with your MongoDB deployment's connection string
28+
String uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
29+
30+
MongoClientSettings settings = MongoClientSettings.builder()
31+
.applyConnectionString(new ConnectionString(uri))
32+
.serverApi(serverApi)
33+
.build();
34+
35+
MongoClient client = MongoClients.create(settings);
36+
// end serverAPIVersion
37+
}
38+
}
39+

0 commit comments

Comments
 (0)