Skip to content

Commit cf04f7c

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-19058 stable api (#111)
* added Stable API page
1 parent d132920 commit cf04f7c

File tree

4 files changed

+155
-1
lines changed

4 files changed

+155
-1
lines changed

‎snooty.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1
1919
version = "v1.10.0-beta1" # always set this to the driver branch (i.e. v1.7.0, v1.8.0, etc.)
2020
example = "https://raw.githubusercontent.com/mongodb/docs-golang/{+docs-branch+}/source/includes/usage-examples/code-snippets"
2121
api = "https://pkg.go.dev/go.mongodb.org/mongo-driver@{+version+}"
22+
stable-api = "Stable API"

‎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/stable-api
1213
/fundamentals/context
1314
/fundamentals/auth
1415
/fundamentals/bson

‎source/fundamentals/stable-api.txt‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
.. _golang-stable-api:
2+
3+
==============
4+
{+stable-api+}
5+
==============
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. note::
16+
17+
The {+stable-api+} feature requires MongoDB Server 5.0 or later.
18+
19+
You should only use the {+stable-api+} feature if all the MongoDB
20+
servers you are connecting to support this feature.
21+
22+
Overview
23+
--------
24+
25+
In this guide, you can learn how to specify **{+stable-api+}**
26+
compatibility when connecting to a MongoDB instance or replica set.
27+
28+
The {+stable-api+} feature forces the server to run operations with
29+
behaviors compatible with the **API version** you specify. An API
30+
version defines the expected behavior of the operations it covers and
31+
the format of server responses. The operations and the server responses
32+
may differ depending on the API version you specify.
33+
34+
When you use the Stable API feature with an official MongoDB driver, you
35+
can update your driver or server without worrying about backward
36+
compatibility issues of the commands covered by the {+stable-api+}.
37+
38+
To learn more about the commands the server covers, see
39+
:manual:`{+stable-api+} </reference/stable-api/>`.
40+
41+
Specify an API Version
42+
----------------------
43+
44+
The ``Client`` optionally takes a ``ServerAPIOptions`` type through
45+
the ``ClientOptions``.
46+
47+
To specify an API version, append the ``SetServerAPIOptions()`` method
48+
with your :ref:`server API options <golang-stable-api-options>` to your
49+
``ClientOptions``. After you specify an API version, the ``Client`` runs
50+
operations that are compatible with the API version for the duration of
51+
your connection.
52+
53+
.. note::
54+
55+
The {+driver-long+} currently only supports ``ServerAPIVersion1``.
56+
57+
Example
58+
~~~~~~~
59+
60+
The following example instantiates a ``Client`` that sets the
61+
{+stable-api+} version and connects to a server.
62+
63+
.. code-block:: go
64+
:copyable: true
65+
66+
// Specify a server URI to connect to
67+
uri := "mongodb://<hostname>:<port>"
68+
69+
// Specify the Stable API version in the ClientOptions object
70+
serverAPI := options.ServerAPI(options.ServerAPIVersion1)
71+
72+
// Pass in the URI and the ClientOptions to the Client
73+
client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI))
74+
if err != nil {
75+
panic(err)
76+
}
77+
78+
.. _golang-stable-api-options:
79+
80+
Modify Behavior
81+
---------------
82+
83+
You can further modify the behavior of the stable API feature by
84+
appending to the ``ServerAPIOptions`` type. If you don't specify any
85+
options, the driver uses the default values for each option.
86+
87+
.. list-table::
88+
:header-rows: 1
89+
:stub-columns: 1
90+
:widths: 30 70
91+
92+
* - Method
93+
- Description
94+
95+
* - ``ServerAPI()``
96+
- | The API version to use.
97+
|
98+
| Default: **ServerAPIVersion1**
99+
100+
* - ``SetStrict()``
101+
- | Flag that indicates whether the server should return errors for features that aren't part of the API version.
102+
|
103+
| Default: **false**
104+
105+
* - ``SetDeprecationErrors()``
106+
- | Flag that indicates whether the server should return errors for deprecated features.
107+
|
108+
| Default: **false**
109+
110+
Example
111+
~~~~~~~
112+
113+
This example specifies for the server to perform the following actions:
114+
115+
- Use Version 1 of the API
116+
- Return errors for features that aren't part of Version 1
117+
- Return errors for deprecated features
118+
119+
.. code-block:: go
120+
:copyable: true
121+
122+
// Specify a server URI to connect to
123+
uri := "mongodb://<hostname>:<port>"
124+
125+
// Specify the Stable API version and append options in the ClientOptions object
126+
serverAPI := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true).SetDeprecationErrors(true)
127+
128+
// Pass in the URI and the ClientOptions to the Client
129+
client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI))
130+
if err != nil {
131+
panic(err)
132+
}
133+
134+
Additional Information
135+
----------------------
136+
137+
To learn more about connecting to your MongoDB instance or replica set,
138+
see :ref:`golang-connection-guide`.
139+
140+
API Documentation
141+
~~~~~~~~~~~~~~~~~
142+
143+
For more information on the options in this section, see the following
144+
API Documentation:
145+
146+
- `Client <{+api+}/mongo/options#Client>`__
147+
- `ClientOptions <{+api+}/mongo/options#ClientOptions>`__
148+
- `ServerAPI() <{+api+}/mongo/options#ServerAPI>`__
149+
- `ServerAPIOptions <{+api+}/mongo/options#ServerAPIOptions>`__
150+
- `ServerApiVersion <{+api+}/mongo/options#ServerAPIVersion>`__
151+
- `SetDeprecationErrors() <{+api+}/mongo/options#ServerAPIOptions.SetDeprecationErrors>`__
152+
- `SetStrict() <{+api+}/mongo/options#ServerAPIOptions.SetStrict>`__

‎source/includes/fundamentals-sections.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@ Learn how to perform the following tasks using the Go driver in the
22
Fundamentals section:
33

44
- :ref:`Connect to MongoDB <golang-connection-guide>`
5+
- :ref:`Specify an API Version <golang-stable-api>`
56
- :ref:`How the Driver Uses Context <golang-context>`
67
- :ref:`Authenticate with MongoDB <golang-authentication-mechanisms>`
78
- :ref:`Read from and Write to MongoDB <golang-crud>`
89
- :ref:`Work with BSON <golang-bson>`
910
- :ref:`Perform Aggregations <golang-aggregation>`
1011
- :ref:`Use a Time Series Collection <golang-time-series>`
1112

12-
.. - :doc:`Specify an API Version </fundamentals/versioned-api>`
1313
.. - :doc:`Use the Driver's Data Formats </fundamentals/data-formats>`
1414
.. - :doc:`Construct Indexes </fundamentals/indexes>`
1515
.. - :doc:`Specify Collations </fundamentals/collations>`

0 commit comments

Comments
 (0)