Stable API
On this page
What is the Stable API, and Should You Use It?
The MongoDB Stable API (previously labeled the Versioned API) lets you upgrade your MongoDB server at will, and ensure that behavior changes between MongoDB versions do not break your application.
MongoDB 5.0 introduces the Stable API for applications communicating with MongoDB server products. The Stable API allows you to specify which version of the MongoDB API your application runs against.
The Stable API provides long-term API stability for applications and supports more frequent releases and automatic server upgrades. This allows your applications to take advantage of rapidly released features without risking backwards-breaking changes.
The default behavior for your driver connection will continue to function as expected, even if you do not explicitly specify an apiVersion.
The Stable API encompasses the subset of MongoDB commands that applications use to read and write data, create collections and indexes, and perform other common tasks.
Note
Starting in February 2022, the "Versioned API" terminology was changed to "Stable API". All concepts and features remain the same with this naming change.
Backward Compatibility Guarantee
Your application will not experience significant behavior changes resulting from server upgrades. This guarantee holds as long as the new server supports your specified API version.
To guarantee backward compatibility, your application must:
Declare an API version
Only use commands and features supported in your specified API version
Deploy with a supported version of an official driver
Declare the API Version
➤ Use the Select your language drop-down menu in the upper-right to set the language of the examples on this page.
To use the Stable API, upgrade to the latest driver and create your application's MongoClient:
"1"
is currently the only API version available.
By default, clients are non-strict. A non-strict client allows you to run any command, regardless of whether or not it belongs to the Stable API.
Checking Client API Versions
Use the serverStatus
command to check for your
application's configured API version. For each application connected to
your MongoDB instance, an appname
appears in the apiVersions
document.
See metrics.apiVersions for more information.
db.runCommand( { serverStatus: 1 } ).metrics.apiVersions
Create a Strict Client
A strict client rejects all commands outside of the Stable API. Attempts to use commands outside of the Stable API will receive the APIVersionError response.
Use the sample code to create a strict client:
Migrate To Stable API Commands
To migrate your application to use the Stable API, you must:
Run your application's test suite with the new MongoClient options.
Determine which commands and features you're using that are outside of the Stable API.
Migrate to alternative commands and features in the Stable API.
Once your application uses only commands and features defined in the Stable API, you can redeploy it with the new MongoClient options and be confident that future server upgrades won't negatively impact your application.
Example: count
Migration
This example shows how to migrate an application that implements the
count
command to an alternative method of counting
documents. Since the count
command does not belong to the
Stable API, this application cannot use the Stable API until the
count
command is removed from the code.
Use the sample code to create a sales
collection in
mongosh
:
db.sales.insertMany([ { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2021-01-01T08:00:00Z") }, { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2021-02-03T09:00:00Z") }, { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-03T09:05:00Z") }, { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2021-02-15T08:00:00Z") }, { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T09:05:00Z") }, { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-15T12:05:10Z") }, { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T14:12:12Z") }, { "_id" : 8, "item" : "abc", "price" : 10, "quantity" : 5, "date" : ISODate("2021-03-16T20:20:13Z") } ])
Stable API Error Response
For example, issuing db.sales.count()
results in this error:
{ "ok" : 0, "errmsg" : "Provided apiStrict:true, but the command count is not in API Version 1", "code" : 323, "codeName" : "APIStrictError" }
However, the aggregate
command is
in the Stable API and can be used to
obtain a count. Use the sample code to obtain a count from the sales
collection in mongosh
:
db.sales.aggregate([ { $group: { _id: null, count: { $count: { } } } } ])
This results in a document where the count
field contains the
number of documents in the collection:
{ "_id" : null, "count" : 8 }
How To Use Commands and Features Outside of the Stable API
To use commands and features outside of the Stable API, you can connect to your deployment with a non-strict client. By default, clients are non-strict.
Use the sample code to create a non-strict client:
Using this non-strict client allows you to run commands outside of the
Stable API. For example, this non-strict client now allows you to
use the count
command once again.
Important
Commands and features outside of the Stable API do not have the same backward compatibility guarantees as versioned alternatives.
API V1 Commands
API V1 protects you from API-breaking changes for the following commands:
createIndexes
(with limitations) [1]
[1] | (1, 2, 3, 4) API V1 may not support all available options for these commands. Refer to the specific command documentation for limitations specific to API V1. |
[2] | MongoDB does not guarantee that the output of the
explain command will conform to the same format in
future API versions. |
Parameters
You can specify the following optional parameters for Stable API in your application's MongoDB driver connection code. Check the MongoDB driver documentation for the driver you use in your application for more information:
Parameter | Type | Description |
---|---|---|
string | API Version. See APIVersionError. | |
boolean | If If not specified, defaults to See APIStrictError. | |
boolean | If If not specified, defaults to |
Behavior
Parameter Validation
Starting in MongoDB 5.0, API V1 database commands raise an error if passed a parameter not explicitly accepted by the command.
In MongoDB 4.4 and earlier, unrecognized parameters are silently ignored.
API Error Responses
This table shows error responses for problematic Stable API requests.
Server Response | Request |
---|---|
Specifies | |
Specifies | |
Specifies an apiVersion that the server does not support. | |
Specifies |