Stable API

¿Qué es la Stable API y deberías usarla?

La Stable API de MongoDB (anteriormente denominada API versionada) te permite actualizar tu servidor de MongoDB cuando quieras y asegurarte de que los cambios de comportamiento entre las versiones de MongoDB no afecten a tu aplicación.

MongoDB 5.0 introduce la Stable API para aplicaciones que se comunican con los productos de servidor de MongoDB. La Stable API te permite especificar con qué versión de la API de MongoDB se ejecuta tu aplicación.

La API estable proporciona estabilidad API a largo plazo para las aplicaciones y soporta lanzamientos más frecuentes y actualizaciones automáticas del servidor. Esto permite que tus aplicaciones aprovechen las funcionalidades lanzadas rápidamente sin correr el riesgo de cambios disruptivos.

El comportamiento por defecto de tu conexión de controlador continuará funcionando como se espera, incluso si no especificas explícitamente un apiVersion.

La API estable abarca el subconjunto de comandos de MongoDB que las aplicaciones utilizan para leer y guardar datos, crear colecciones e índices y realizar otras tareas habituales.

Nota

A partir de febrero de 2022, la terminología "API versionada" cambió a "API estable". Todos los conceptos y funcionalidades siguen siendo los mismos con este cambio de nombre.

Garantía de compatibilidad con versiones anteriores

Su aplicación no experimentará cambios significativos de comportamiento como resultado de las actualizaciones del servidor. Esta garantía se mantiene mientras el nuevo servidor sea compatible con la versión de API especificada.

Para garantizar la compatibilidad con versiones anteriores, tu aplicación debe:

Declarar una versión de API
Sólo use los comandos y funcionalidades que estén soportados en su versión especificada de la API
Implementar con una versión compatible de un driver oficial

Declarar la versión de la API

➤ Usar el menú desplegable Seleccionar lenguaje en la parte superior derecha para establecer el lenguaje de los ejemplos en esta página.

Para utilizar la API estable, actualice al controlador más reciente y cree el MongoClient de su aplicación:

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;

val serverApi = ServerApi.builder()
    .version(ServerApiVersion.V1)
    .build()
val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .serverApi(serverApi)
    .build()
val client = MongoClient.create(settings)

    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" es actualmente la única versión de API disponible.

De forma predeterminada, los clientes no son estrictos. Un cliente no estricto permite ejecutar cualquier comando, independientemente de si pertenece o no a la API estable.

Verificación de versiones de la API cliente

Usa el serverStatus comando para comprobar la versión API configurada de tu aplicación. Para cada aplicación conectada a tu instancia de MongoDB, aparece un appname en el documento apiVersions.

Ver métricas.apiVersions para más información.

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

Crear un cliente estricto

Un cliente estricto rechaza todos los comandos fuera de la API estable.Cualquier intento de usar comandos fuera de la API estable recibirá la respuesta APIVersionError.

Un cliente estricto también ignora tipos de índices no compatibles durante la planificación y ejecución de consultas.

Usa el código de muestra para crear un cliente estricto:

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;

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

    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 a comandos de API estables

Para migrar su aplicación para usar la Stable API, debe:

Ejecute la suite de pruebas de su aplicación con las nuevas opciones de MongoClient.
Determina qué comandos y funcionalidades estás usando que están fuera de la Stable API.
Migrar a comandos y funciones alternativos en la API estable.

Una vez que tu aplicación use únicamente los comandos y funcionalidades definidos en la Stable API, puedes volver a implementarla con las nuevas opciones de MongoClient y tener la confianza de que las futuras actualizaciones del servidor no impactarán negativamente tu aplicación.

Cómo utilizar los comandos y funcionalidades fuera de la Stable API

Para usar comandos y funcionalidades fuera de la Stable API, puedes conectarte a tu implementación con un cliente no estricto. Por defecto, los clientes son no estrictos.

Para crear un cliente no estricto, utilice el siguiente código de muestra:

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()
        );

val serverApi = ServerApi.builder()
    .version(ServerApiVersion.V1)
    .strict(false)
    .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 este cliente no estricto te permite ejecutar comandos fuera de la Stable API. Por ejemplo, este cliente no estricto te permite ejecutar el comando createUser.

Importante

Los comandos y funcionalidades fuera de la Stable API no tienen las mismas garantías de compatibilidad con versiones anteriores que las alternativas versionadas.

Stable API Commands

Los comandos de base de datos incluidos en la Stable API V1 dependen de la versión de MongoDB que estés utilizando. Para ver los comandos de base de datos incluidos en la Stable API y la versión de MongoDB en la que se introdujeron, consulta el registro de cambios de la Stable API.

Parámetros

Puede especificar los siguientes parámetros opcionales para la API estable en el código de conexión del controlador MongoDB de su aplicación. Para más información, consulte la documentación del controlador MongoDB que utiliza en su aplicación:

Parameter	Tipo	Descripción
apiVersion	string	Especifica la versión de la API. Actualmente, `"1"` es la única versión soportada.
apiStrict	booleano	En caso de que `true`: El uso de un comando que no forma parte de la versión declarada de la API devuelve un error APIStrictError. El planificador de query ignora los índices no compatibles con la Stable API. Si especifica apiStrict, también debe especificar apiVersion. Si no se especifica, el valor por defecto es `false`.
apiDeprecationErrors	booleano	Si `true` es, al usar un comando o comportamiento obsoleto en la versión de API especificada, se devuelve un error APIDeprecationError. Si especifica apiDeprecationErrors, también debe especificar apiVersion. Si no se especifica, el valor por defecto es `false`.

Comportamiento

Parameter Validation

A partir de MongoDB 5.0, los comandos de base de datos de la API versión 1 generan un error si se pasa un parámetro que no es explícitamente aceptado por el comando.

Respuestas de errores de la API estable

Esta tabla muestra las respuestas de error para solicitudes problemáticas de la API estable.

Respuesta del servidor	Solicitud
APIDeprecationError	Especifica `{ apiDeprecationErrors: true }` con la versión de API `V` y utiliza un comportamiento obsoleto en `V`.
APIStrictError	Especifica `{ apiStrict: true }` con la versión `V` de la API, pero utiliza una conducta que no está presente en la versión `V`.
APIVersionError	Especifica una apiVersion que el servidor no admite.
Opciones no válidas	Especifica `{ apiStrict: true }` o `{ apiDeprecationErrors: true }` pero omite apiVersion.

Volver

Motor de ejecución de query basado en ranuras

Migrar a una versión posterior