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:
"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 API estável. As tentativas de usar comandos fora da API Stable receberão a resposta APIVersionError .
Use o código de amostra para criar um cliente rigoroso:
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:
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 |
|---|---|---|
string | Especifica a versão da API. "1" é atualmente a única versão suportada. | |
booleano | Se Se não for especificado, o padrão será | |
booleano | Se Se não for especificado, o padrão será |
Comportamento
Validação de parâmetros
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 |
|---|---|
Especifica | |
Especifica | |
Especifica uma apiVersion que o servidor não suporta. | |
Especifica |