Docs Menu

Versioned API

On this page

  • Overview
  • Enable the Versioned API on a MongoDB Client
  • Versioned API Options
Note

The Versioned API feature requires MongoDB Server 5.0 or later.

You should only use the Versioned API feature if all the MongoDB servers you are connecting to support this feature.

In this guide, you can learn how to specify the Versioned API when connecting to a MongoDB instance or replica set. You can use the Versioned API feature to force the server to run operations with behavior compatible with the specified API version. An API version defines the expected behavior of the operations it covers and the format of server responses. If you change to a different API version, the operations are not guaranteed to be compatible and the server responses are not guaranteed to be similar.

When you use the Versioned API feature with an official MongoDB driver, you can update your driver or server without worrying about backward compatibility issues of the commands covered by the Versioned API.

See the server manual page on the Versioned API for more information including a list of commands it covers.

The following sections describe how you can enable the Versioned API for your MongoDB client and the options that you can specify.

To enable the Versioned API, you must specify an API version in the MongoClientOptions passed to your MongoClient. Once you instantiate a MongoClient instance with a specified API version, all commands you run with that client use that version of the Versioned API.

Tip

If you need to run commands using more than one version of the Versioned API, instantiate a separate client with that version.

If you need to run commands not covered by the Versioned API, make sure the "strict" option is disabled. See the section on Versioned API Options for more information.

The example below shows how you can instantiate a MongoClient that sets the Versioned API version and connects to a server by performing the following operations:

  • Specify a server URI to connect to.
  • Specify a Versioned API version in the MongoClientOptions object, using a constant from the ServerApiVersion object.
  • Instantiate a MongoClient, passing the URI and the MongoClientOptions to the constructor.
const { MongoClient, ServerApiVersion } = require("mongodb");
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });
Warning

If you specify an API version and connect to a MongoDB server that does not support the Versioned API, your application may throw an error when connecting to your MongoDB server with the following text:

MongoParseError: Invalid server API version=...

For more information on the methods and classes referenced in this section, see the following API Documentation:

You can enable or disable optional behavior related to the Versioned API as described in the following table.

Option Name
Description
version
Required. Specifies the version of the Versioned API.

Default: null
strict
Optional. When set, if you call a command that is not part of the declared API version, the driver raises an exception.

Default: false
deprecationErrors
Optional. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception.

Default: false

The following example shows how you can set the options of the ServerApi interface.

const { MongoClient, ServerApiVersion } = require("mongodb");
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri,
{
serverApi: {
version: ServerApiVersion.v1,
strict: true,
deprecationErrors: true,
}
});

For more information on the options in this section, see the following API Documentation:

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

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