¿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 driver seguirá funcionando como se espera, incluso si no especificas explícitamente una 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 experimenta cambios significativos de comportamiento debido a las actualizaciones del servidor. Esta garantía se mantiene si el nuevo servidor es 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
Para utilizar la Stable API, actualiza al último driver y crea el MongoClient de tu aplicación:
"1" es actualmente la única versión de API disponible.
Por defecto, los clientes son no estrictos. Un cliente no estricto permite ejecutar cualquier comando, independientemente de si pertenece o no a la Stable API.
Verificación de versiones de la API cliente
Utiliza el comando serverStatus para verificar 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
Crea un cliente estricto
Un cliente estricto rechaza todos los comandos fuera de la Stable API. Los intentos de utilizar comandos fuera de la Stable API recibirán 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:
Migra a comandos Stable API
Para migrar su aplicación para usar la Stable API, debe:
Ejecute el conjunto 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.
Migra a comandos y funciones alternativos en la Stable API.
Una vez que su aplicación utilice únicamente los comandos y funcionalidades definidos en la Stable API, puede volver a implementarla con las nuevas opciones de MongoClient y tener la confianza de que las futuras actualizaciones del servidor no impactarán negativamente su 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:
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
Puedes especificar los siguientes parámetros opcionales para la Stable API en el código de conexión de tu aplicación al driver de MongoDB. Consulte la documentación del controlador de MongoDB correspondiente al controlador que utiliza en su aplicación para obtener más información:
Parameter | Tipo | Descripción |
|---|---|---|
string | Especifica la versión de la API. Actualmente, | |
booleano |
Si especifica apiStrict, también debe especificar apiVersion. Si no se especifica, el valor por defecto es | |
booleano | Si Si no se especifica, el valor por defecto es |
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 |
|---|---|
Especifica | |
Especifica | |
Especifica un apiVersion que el servidor no admite. | |
Especifica |