Stable API

Nesta página

O que é a API estável e você deve usá-la?

Garantia de compatibilidade com versões anteriores
Declare a versão da API
Verificando versões da API do cliente
Criar um cliente rigoroso
Migrar para comandos de API estáveis
Como usar comandos e recursos fora da API estável
Comandos de API estáveis
Parâmetros
Comportamento
Respostas de erro de API estáveis

O que é a API estável e você deve usá-la?

A API estável MongoDB (anteriormente denominada API versionada) permite atualizar seu servidor MongoDB e garantir que as alterações de comportamento entre as versões MongoDB não quebrem seu aplicativo.

O MongoDB 5.0 introduz a API estável para aplicativos que se comunicam com produtos de servidor MongoDB. A API Stable permite que você especifique em qual versão da API do MongoDB seu aplicativo é executado.

A API estável oferece estabilidade de API a longo prazo para aplicativos e oferece suporte a versões mais frequentes e atualizações automáticas do servidor. Isso permite que seus aplicativos aproveitem os recursos lançados rapidamente sem correr o risco de alterações retrógradas.

O comportamento padrão da conexão do driver continuará funcionando conforme o esperado, mesmo que você não especifique explicitamente umaAPIVersion .

A Stable API engloba o subconjunto de comandos MongoDB que os aplicativos usam para ler e gravar dados, criar coleções e índices e executar outras tarefas comuns.

Observação

A partir de fevereiro de 2022, a terminologia "API versionada" foi alterada para "API estável". Todos os conceitos e funcionalidades permanecem os mesmos com essa mudança de nomenclatura.

Garantia de compatibilidade com versões anteriores

Seu aplicativo não sofrerá alterações significativas de comportamento resultantes de atualizações do servidor. Esta garantia é válida enquanto o novo servidor suportar a versão da API especificada.

Para garantir compatibilidade com versões anteriores, seu aplicativo deve:

Declare uma versão da API
Use apenas comandos e recursos suportados na versão da API especificada
Implemente com uma versão suportada de um driver oficial

Declare a versão da API

➤ Use o menu suspenso Selecione a linguagem no canto superior direito para definir a linguagem dos exemplos nesta página.

Para usar a API Stable, atualize para o driver mais recente e crie o MongoClient da sua aplicação:

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")};
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIExample is an example of creating a client with stable API.
func StableAPIExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build()
                ).build()
        );
return client;

    from pymongo.server_api import ServerApi
    client = AsyncIOMotorClient(uri, server_api=ServerApi("1"))

client = new MongoClient(uri, { serverApi: { version: '1' } });

$serverApi = new \MongoDB\Driver\ServerApi('1');
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

from pymongo.server_api import ServerApi
MongoClient(uri, server_api=ServerApi("1"))

client = Mongo::Client.new(uri_string, server_api: {version: "1"})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, options: opts)

"1" atualmente é a única versão disponível da API.

Por padrão, os clientes são não rigorosos. Um cliente não rigoroso permite que você execute qualquer comando, independentemente de pertencer ou não à API estável.

Verificando versões da API do cliente

Use o comando serverStatus para verificar a versão da API configurada do seu aplicativo. Para cada aplicativo conectado à instância do MongoDB, um appname aparece no documento apiVersions.

Consulte metrics.apiVersions para obter mais informações.

db.runCommand( { serverStatus: 1 } ).metrics.apiVersions

Criar um cliente rigoroso

Um cliente rigoroso rejeita todos os comandos fora da Stable API. As tentativas de usar comandos fora da Stable API receberão a resposta APIVersionError.

Um cliente estrito também ignora tipos de índice não suportados durante o planejamento da query e sua execução.

Use o código de amostra para criar um cliente rigoroso:

mongosh --apiVersion 1 --apiStrict

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, true);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(true);  // Enable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: true);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIStrictExample is an example of creating a client with strict stable API.
func StableAPIStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(true)
                .build()
                ).build()
        );
return client;

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=True))

client = new MongoClient(uri, { serverApi: { version: '1', strict: true } });

$serverApi = new \MongoDB\Driver\ServerApi('1', true);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=True))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: true})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(true)
    .build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, options: opts)

Migrar para comandos de API estáveis

Para migrar seu aplicativo para usar a API estável, você deve:

Execute o conjunto de testes da sua aplicação com as novas opções do MongoClient.
Determine quais comandos e recursos você está usando que estão fora da API estável.
Migre para comandos e recursos alternativos na API estável.

Depois que seu aplicativo usar apenas comandos e recursos definidos na API estável, você poderá implementá-lo novamente com as novas opções MongoClient e ter certeza de que futuras atualizações de servidor não afetarão negativamente seu aplicativo.

Como usar comandos e recursos fora da API estável

Para usar comandos e recursos fora da API estável, você pode se conectar à sua implantação com um cliente não rigoroso. Por padrão, os clientes são não rigorosos.

Para criar um cliente não rigoroso, use o seguinte código de amostra:

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, false);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(false);  // Explicitly disable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: false);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPINonStrictExample is an example of creating a client with non-strict stable API.
func StableAPINonStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(false)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(false)
                .build()
                ).build()
        );

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=False))

client = new MongoClient(uri, { serverApi: { version: '1', strict: false } });

$serverApi = new \MongoDB\Driver\ServerApi('1', false);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=False))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: false})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(false)
    .build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, options: opts)

Usar esse cliente não rigoroso permite que você execute comandos fora da API estável. Por exemplo, este cliente não rigoroso permite a você executar o comando createUser.

Importante

Os comandos e recursos fora da API estável não têm as mesmas garantias de compatibilidade com versões anteriores que as alternativas com controle de versão.

Comandos de API estáveis

Os comandos do banco de dados incluídos no Stable API V1 dependem da versão MongoDB que você está usando. Para exibir os comandos de banco de dados incluídos na API estável e na versão do MongoDB que foram introduzidos, consulte Log de alterações da API estável.

Parâmetros

Você pode especificar os parâmetros opcionais a seguir para API estável no código de conexão do driver MongoDB do seu aplicativo. Verifique a documentação do driver MongoDB para o driver que você usa em seu aplicativo para obter mais informações:

Parâmetro	Tipo	Descrição
apiVersion	string	Especifica a versão da API. `"1"` é atualmente a única versão suportada.
apiStrict	booleano	Se `true`: Usar um comando que não faz parte da versão declarada da API retorna um erro APIStrictError . Os índices que não são suportados pela Stable API são ignorados pelo planejador de query. Se você especificar apiStrict, também deverá especificar apiVersion. Se não for especificado, o padrão será `false`.
apiDeprecationErrors	booleano	`true`Se, o uso de um comando ou comportamento que está obsoleto na versão da API especificada retornará um ApiDeprecationError. Se você especificar apiDeprecationErrors, você também deverá especificar apiVersion. Se não for especificado, o padrão será `false`.

Comportamento

Parameter Validation

A partir do MongoDB 5.0, os comandos do banco de dados API V1 geram um erro se for passado um parâmetro não aceito explicitamente pelo comando.

Respostas de erro de API estáveis

Esta tabela mostra respostas de erro para solicitações problemáticas da API estável.

Resposta do servidor	Solicitar
APIDeprecationError	Especifica `{ apiDeprecationErrors: true }` com a API versão `V` e usa um comportamento obsoleto em `V`.
APIStrictError	Especifica `{ apiStrict: true }` com a versão da API `V`, mas utiliza um comportamento que não está na versão `V`.
APIVersionError	Especifica uma apiVersion que o servidor não suporta.
InvalidOptions	Especifica `{ apiStrict: true }` ou,`{ apiDeprecationErrors: true }` mas omite apiVersion.

Voltar

Sessões do servidor

Migrar para uma versão posterior