Stable API

Visão geral

Neste guia, você pode aprender a especificar a API estável ao se conectar a uma instância do MongoDB ou a um conjunto de réplicas. Você pode usar o recurso API estável para forçar o servidor a executar operações com comportamento compatível com a versão da API especificada. Uma versão da API define o comportamento esperado das operações que ela cobre e o formato das respostas do servidor. Se você alterar para uma versão de API diferente, as operações não terão garantia de serem compatíveis e as respostas do servidor não terão garantia de serem semelhantes.

Quando você usa o recurso API estável com um driver oficial do MongoDB, você pode atualizar seu driver ou servidor sem se preocupar com compatibilidade com versões anteriores problemas dos comandos cobertos pela API estável.

Consulte a página de referência do MongoDB na Stable API para obter mais informações, incluindo uma lista de comandos que ela abrange.

As seções a seguir descrevem como você pode habilitar a API estável para seu cliente MongoDB e as opções que você pode especificar.

Habilitar a API estável em um cliente MongoDB

Para habilitar a API estável, você deve especificar uma versão da API no MongoClientOptions passado para seu MongoClient. Depois de instanciar uma instância MongoClient com uma versão de API especificada, todos os comandos que você executa com essa versão da API estável.

O exemplo abaixo mostra como você pode instanciar um MongoClient que define a versão da API estável e se conecta a um servidor executando as seguintes operações:

• Especifique um URI do servidor ao qual se conectar.

• Especifique uma versão de API estável no objeto MongoClientOptions, usando uma constante do objeto ServerApiVersion.

• Instancie um MongoClient, passando o URI e o MongoClientOptions para o construtor.

const { MongoClient, ServerApiVersion } = require("mongodb");
// Replace the placeholders in the connection string uri with your credentials
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
// Create a client with options to specify Stable API Version 1
const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });

MongoParseError: Invalid server API version=...

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• ServerApiVersion

• MongoClientOptions

• Cliente Mongo

Opções de API estáveis

Você pode habilitar ou desabilitar o comportamento opcional relacionado à API estável como descrito na tabela a seguir.

O exemplo a seguir mostra como você pode definir as opções da interface do ServerApi.

const { MongoClient, ServerApiVersion } = require("mongodb");
// Replace the placeholders in the connection string uri with your credentials
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
/* Create a client with options to specify Stable API Version 1, return
errors for commands outside of the API version, and raise exceptions
for deprecated commands */
const client = new MongoClient(uri,
    {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true,
        }
    });

Para obter mais informações sobre as opções nesta seção, consulte a seguinte documentação da API:

• API do servidor