Stable API
On this page
Note
The Stable API feature requires MongoDB Server 5.0 or later.
Overview
In this guide, you can learn how to specify Stable API compatibility when connecting to a MongoDB deployment.
The Stable API feature forces the server to run operations with behaviors compatible with the API version you specify. Using the Stable API ensures consistent responses from the server and provides long-term API stability for your application.
The following sections describe how you can enable and customize the Stable API for your MongoDB client. For more information about the Stable API, including a list of the commands it supports, see Stable API in the MongoDB Server manual.
Enable the Stable API
To enable the Stable API, pass a hash that specifies the Stable API version to the optional
server_api parameter when you create a Mongo::Client instance.
The following code example shows how to specify Stable API version 1:
client = Mongo::Client.new(uri, server_api: { version: '1' })
Once you create a Client instance with
a specified API version, all commands that you run with the client use the specified
version. If you must run commands using more than one version of the
Stable API, create a new Client.
Configure the Stable API
The following table describes Stable API options that you can set by specifying
them in the server_api hash. You can use these options to customize the behavior of the
Stable API.
Option Name | Description |
|---|---|
strict | Optional. When true, if you call a command that isn't part of
the declared API version, the driver raises an exception.Default: false |
deprecation_errors | Optional. When true, if you call a command that is deprecated in the
declared API version, the driver raises an exception.Default: false |
The following code example shows how you can set the two options on a ServerApi instance:
client = Mongo::Client.new(uri, server_api: { version: '1', strict: true, deprecation_errors: true })
Troubleshooting
The following sections describe common issues you might encounter when using the Stable API.
Unrecognized field 'apiVersion' on server
The Ruby driver raises this exception if you specify an API version and connect to a MongoDB server that doesn't support the Stable API. Ensure you're connecting to a deployment running MongoDB Server v5.0 or later.
Provided apiStrict:true, but the command count is not in API Version
The Ruby driver raises this exception if your Client runs an operation that
isn't in the Stable API version you specified. To avoid this error, use an alternative
operation supported by the specified Stable API version, or set the strict
option to false when constructing your ServerApi object.
API Documentation
For more information about using the Stable API with the Ruby driver, see the following API documentation: