Stable API

¿Qué es la API estable y debería utilizarla?

La API estable de MongoDB (anteriormente denominada API versionada) le permite actualizar su servidor MongoDB a voluntad y garantizar que los cambios de comportamiento entre versiones de MongoDB no dañen su aplicación.

MongoDB 5.0 presenta la API estable para aplicaciones que se comunican con productos de servidor MongoDB. Esta API permite especificar la versión de la API de MongoDB con la que se ejecuta la 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 predeterminado para la conexión de su controlador seguirá funcionando como se espera, incluso si no especifica explícitamente un apiVersión.

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

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, su aplicación debe:

Declarar una versión de API
Utilice únicamente comandos y funciones compatibles con la versión de API especificada
Implementar con una versión compatible de un controlador 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;

    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" Actualmente es 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.

Comprobación de las versiones de la API del cliente

Uso el serverStatus Comando para verificar la versión de la API configurada de su aplicación. Para cada aplicación conectada a su instancia de MongoDB,appname aparece un en el apiVersions documento.

Consulte metrics.apiVersions para obtener 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 los tipos de índice no admitidos durante la planificación y ejecución de consultas.

Utilice 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;

    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 utilizar la API estable, debe:

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

Una vez que su aplicación use solo comandos y características definidos en la API estable, puede volver a implementarla con las nuevas opciones de MongoClient y tener la seguridad de que las futuras actualizaciones del servidor no afectarán negativamente su aplicación.

Cómo usar comandos y funciones fuera de la API estable

Para usar comandos y funciones fuera de la API estable, puede conectarse a su implementación con un cliente no estricto. De forma predeterminada, los clientes no son 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()
        );

    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 permite ejecutar comandos fuera de la API estable. Por ejemplo, permite ejecutar el createUser comando.

Importante

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

Comandos API estables

Los comandos de base de datos incluidos en la API estable V1 dependen de la versión de MongoDB que utilice. Para ver los comandos de base de datos incluidos en la API estable y la versión de MongoDB en la que se introdujeron, consulte el registro de cambios de la API estable.

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. `"1"` es actualmente la única versión compatible.
API estricta	booleano	Si `true`: El uso de un comando que no es parte de la versión de API declarada devuelve un error APIStrictError. El planificador de consultas ignora losíndices que no son compatibles con la API estable. Si especifica apiStrict, también debe especificar apiVersion. Si no se especifica, el valor predeterminado es `false`.
Errores de desuso de API	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 predeterminado es `false`.

Comportamiento

Parameter Validation

A partir de MongoDB 5.0, los comandos de base de datos API V1 generan un error si se pasa un parámetro no aceptado explícitamente por el comando.

Respuestas de error de API estables

Esta tabla muestra respuestas de error para solicitudes de API estables problemáticas.

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 de API `V`, pero utiliza un comportamiento que no está 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