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 stable API, você deve especificar uma versão da API nas configurações do seu cliente MongoDB. Depois de instanciar uma instância do MongoClient com uma versão de API especificada, todos os comandos que você executa com esse cliente usam essa versão da API estável.

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

• Construa uma instância ServerApi usando a classe auxiliar ServerApi.Builder .

• Especifique uma versão de API estável usando uma constante da classe ServerApiVersion .

• Construa uma instância MongoClientSettings usando a classe MongoClientSettings.Builder .

• Especifique um servidor para se conectar usando uma instância ServerAddress .

• Instancie um MongoClient utilizando o método MongoClients.create() e passe sua instância do MongoClientSettings como um parâmetro.

ServerApi serverApi = ServerApi.builder()
        .version(ServerApiVersion.V1)
        .build();
// Replace the uri string with your MongoDB deployment's connection string
String uri = "<connection string uri>";
MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(uri))
        .serverApi(serverApi)
        .build();
MongoClient client = MongoClients.create(settings);

'Unrecognized field 'apiVersion' on server...

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

• API do servidor

• ServerApi.Builder

• ServerApiVersion

• ServerAddress

• Configurações do Mongo Client

• MongoClientSettings.Builder

• MongoClients.create()

• 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 duas opções em uma instância de ServerApi encadeando métodos no ServerApi.Builder:

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

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

• strict()

• deprecationErrors()