Stable API

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 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, perform the following steps:

1. Construct a ServerApi object and specify a Stable API version. You must use a Stable API version defined in the ServerApiVersion enum.

2. Construct a MongoClientSettings object using the MongoClientSettings.Builder class.

3. Instantiate a MongoClient using the MongoClients.create() method and pass your MongoClientSettings instance as a parameter.

The following code example shows how to specify Stable API version 1:

ServerApi serverApi = ServerApi.builder()
        .version(ServerApiVersion.V1)
        .build();
// Replace the placeholder with your Atlas connection string
String uri = "<connection string URI>";
MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(uri))
        .serverApi(serverApi)
        .build();
try (MongoClient mongoClient = MongoClients.create(settings)) {
    // Perform client operations here
}

Once you create a MongoClient instance with the Stable API, all commands you run with the client use the specified Stable API configuration. If you must run commands using alternative configurations, create a new MongoClient.

Configure the Stable API

The following table describes chainable methods of the ServerApi.Builder class that you can use to customize the behavior of the Stable API.

The following code example shows how you can configure an instance of ServerApi by chaining methods on the ServerApi.Builder:

ServerApi serverApi = ServerApi.builder()
    .version(ServerApiVersion.V1)
    .strict(true)
    .deprecationErrors(true)
    .build();

Troubleshooting

API Documentation

For more information about using the Stable API with the Java Reactive Streams driver, see the following API documentation:

• ServerApi

• ServerApi.Builder

• ServerApiVersion

• ServerAddress

• MongoClientSettings

• MongoClientSettings.Builder

• MongoClients