Stable API

Overview

En esta guía, puede aprender cómo especificar la Stable API al conectarse a una instancia de MongoDB o a un set de réplicas. Puedes usar la funcionalidad Stable API para forzar que el servidor ejecute operaciones con un comportamiento compatible con la versión de API especificada. Una versión de API define el comportamiento esperado de las operaciones que cubre y el formato de las respuestas del servidor. Si cambias a una versión diferente de la API, no se garantiza que las operaciones sean compatibles y no se garantiza que las respuestas del servidor sean similares.

Cuando utilices la funcionalidad Stable API con un driver oficial de MongoDB, podrás actualizar tu driver o servidor sin preocuparte por problemas de retrocompatibilidad de los comandos cubiertos por la Stable API.

Consulta la página de referencia de MongoDB sobre la Stable API para obtener más información, incluida una lista de los comandos que cubre.

Las siguientes secciones describen cómo se puede habilitar la Stable API para el cliente de MongoDB y las opciones que se pueden especificar.

Habilita la Stable API en un cliente de MongoDB

Para habilitar la Stable API, debes especificar una versión de la API en el MongoClientOptions que se pasa a tu MongoClient. Una vez que se instancie una instancia de MongoClient con una versión de API especificada, todos los comandos que se ejecuten con ese cliente utilizarán esa versión de la Stable API.

El siguiente ejemplo muestra cómo puedes instanciar un MongoClient que establece la versión Stable API y se conecta a un servidor realizando las siguientes operaciones:

• Especifica una URI de servidor a la que conectarte.

• Especifique una versión de Stable API en el objeto MongoClientOptions, utilizando una constante del objeto ServerApiVersion.

• Instancia un MongoClient, pasando el URI y el MongoClientOptions al constructor.

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 obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• ServerApiVersion

• MongoClientOptions

• MongoClient

Opciones de Stable API

Puedes habilitar o deshabilitar el comportamiento opcional relacionado con la Stable API como se describe en la siguiente tabla.

El siguiente ejemplo muestra cómo puedes configurar las opciones de la interfaz 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 obtener más información sobre las opciones de esta sección, consulta la siguiente documentación de la API:

• ServerApi