Docs Menu

Versioned API

On this page

The MongoDB 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 Versioned API for applications communicating with MongoDB server products. The Versioned API allows you to specify which version of the MongoDB API your application runs against.

The Versioned 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 Versioned API encompasses the subset of MongoDB commands that applications use to read and write data, create collections and indexes, and perform other common tasks.

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

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 Versioned 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 Versioned API.

A strict client rejects all commands outside of the Versioned API. Attempts to use commands outside of the Versioned API will receive the APIVersionError response.

Use the sample code to create a strict client:

To migrate your application to use the Versioned API, you must:

  1. Run your application's test suite with the new MongoClient options.
  2. Determine which commands and features you're using that are outside of the Versioned API.
  3. Migrate to alternative commands and features in the Versioned API.

Once your application uses only commands and features defined in the Versioned API, you can redeploy it with the new MongoClient options and be confident that future server upgrades won't negatively impact your application.

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 Versioned API, this application cannot use the Versioned API until the count command is removed from the code.

Use the sample MQL (MongoDB Query Language) 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") }
])

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 Versioned API and can be used to obtain a count. Use the sample MQL (MongoDB Query Language) 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 }

To use commands and features outside of the Versioned 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 Versioned API. For example, this non-strict client now allows you to use the count command once again.

Important

Commands and features outside of the Versioned API do not have the same backward compatibility guarantees as versioned alternatives.

API V1 protects you from API-breaking changes for the following commands:

You can specify the following optional parameters for Versioned 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. "1" is currently the only supported API Version.

See APIVersionError.

boolean

If true, your application can only use commands defined for your specified apiVersion.

If not specified, defaults to false.

See APIStrictError.

boolean

If true, your application errors if it invokes a command or behavior that is deprecated in the specified apiVersion.

If not specified, defaults to false.

See APIDeprecationError.

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.

This table shows error responses for problematic Versioned API requests.

Server Response
Request

Specifies { apiDeprecationErrors: true } with API version V and uses a behavior deprecated in V.

Specifies { apiStrict: true } with API version V, but uses a behavior not in version V.

Specifies an apiVersion that the server does not support.

Specifies { apiStrict: true } or { apiDeprecationErrors: true } but omits apiVersion.

Select your language

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.