Menu Docs
Página inicial do Docs
/
MongoDB Atlas
/
Acesso programático
/
API de administração do Atlas

Migrar para a nova API de administração do Atlas versionado

Nesta página

  • Introdução à API de administração do Atlas versionado
  • Ciclo de vida da API de administração do Atlas versionado
  • Procedimento

Com a introdução da API de administração do Atlas versionado (referida aqui como /v2 ), recomendamos que você migre da API de administração do Atlas herdada (conhecida como /v1 ) para a nova API de administração do Atlas versionado ( /v2 ).

Introdução à API de administração do Atlas versionado

A nova versão da API de administração do Atlas oferece uma experiência geral significativamente melhor no acesso ao Atlas programaticamente. A API de administração do Atlas versionada oferece uma experiência previsível e consistente com alterações de API e melhor visibilidade de novos recursos e alterações.

Ciclo de vida da API de administração do Atlas versionado

O Atlas expõe uma nova versão de recursos de um endpoint deAPI existente quando o Atlas introduz alterações significativas na versão atual estável do endpoint de API . Quando o Atlas expõe uma nova versão do recurso, o Atlas automaticamente descontinua a versão antiga do recurso. O Atlas exclui automaticamente a versão de recurso obsoleta 12 meses após a descontinuação. Embora o Atlas continue a oferecer suporte à versão mais antiga do recurso para uso em seu ambiente de produção por até 12 meses, você deve migrar para a nova versão do endpoint da API o mais rápido possível. Para saber mais, consulte o exemplo noEsquema de Versãodo .

Observe que, com o controle de versão em nível de recurso, cada recurso na API de administração do Atlas versionada pode introduzir uma nova versão independentemente de outros recursos. Você deve tomar ação somente quando os recursos que está utilizando forem preteridos.

Exemplo

Suponha que o Atlas introduza o novo recurso /serverless em 01/06/2023, mas /backup não tem nenhuma alteração interruptiva e permanece em 01/02/2023. Você deve migrar para 2023-06-01 somente se estiver utilizando o recurso /serverless . Se você não implementou o recurso /serverless , não precisará executar nenhuma ação.

O Atlas suporta a versão de recursos obsoleta por pelo menos 12 meses até que ela seja removida, o que lhe dá tempo para planejar e fazer a transição para a nova versão. Você pode ver alterações em cada novo recurso no API Changelog e nos detalhes da versão da API na especificação da API.

Procedimento

Para migrar para a nova API de administração do Atlas versionado, você deve fazer o seguinte:

1

Especifique o número que representa a API versionada no URL base do recurso.

URL base
https://cloud.mongodb.com/api/atlas/<version-number>/

Exemplo

Considere a seguinte URL base para a versão legada de um recurso da API de Administração do Atlas:

https://cloud.mongodb.com/api/atlas/v1.0/

Com a introdução da API de administração versionada, o URL base anterior indica que você está usando recursos que não são versionados. Para enviar uma solicitação para o recurso API de administração do Atlas versionado (/v2), você deve enviar sua solicitação para a seguinte URL base:

https://cloud.mongodb.com/api/atlas/v2/

Para saber mais sobre como enviar solicitações para pontos de conexão da API de administração do Atlas em diferentes estados, consulte Esquema de controle de versão.

2

Adicione o Accept cabeçalho de controle de versão às solicitações.

Para usar a API de administração do Atlas versionada, você deve fornecer uma versão de recurso para seus recursos. A primeira versão é a mesma em todos os recursos e, para a migração inicial da API legada não versionada para a API versionada, você deve usar o número da versão que corresponde à data da versão do recurso.

Exemplo

O comando curl a seguir é um exemplo de uma solicitação para um endpoint da API de administração do Atlas (v2) versionado com o cabeçalho:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --request {GET|DELETE}
  "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"

Você também deve especificar o tipo de conteúdo para solicitações POST, PUT ou PATCH . O valor do tipo de conteúdo pode ser um dos seguintes:

  • application/json

  • application/vnd.atlas.{yyyy-mm-dd}+json

Exemplo

O comando curl a seguir é um exemplo de uma solicitação para um endpoint da API de administração do Atlas (v2) com o cabeçalho e o tipo de conteúdo:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Content-Type: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --request {POST|PUT|PATCH}
  "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"

Para saber mais sobre cabeçalhos de API de administração do Atlas versionados, consulte ciclo de vida da API em Esquema de versionamento.

3

Revise o changelog para determinar as alterações de sintaxe para o ponto de extremidade da API de administração do Atlas na nova versão do recurso.

Novas versões de recursos de endpoints de API podem incluir alteração interruptiva. Certifique-se de que sua solicitação para o novo recurso incorpore essas alterações e que o cabeçalho da solicitação inclua o estado do endpoint para o qual você está enviando a solicitação.

Observação

Você não precisa verificar o Changelog da API para a migração inicial da API de administração do Atlas não versionada para a API de administração do Atlas versionada na versão do recurso 2023-02-01 , a menos que esteja migrando o recurso /v1.0/clusters para a versão Recurso de API de administração do Atlas (v2) /clusters . A versão inicial da API de administração do Atlas versionada em 2023-02-01 contém alterações de sintaxe apenas para o recurso /clusters . Para saber mais, consulte Especificação da API paraClusters .

4

(Opcional) Migre o recurso não versionado da API de administração do Atlas v1.0 Clusters para o recurso de clusters da API de administração do Atlas (v2) versionado.

A versão 2023-02-01 da API de administração do Atlas versionada contém as seguintes alterações de sintaxe para o recurso Clusters :

Tipo de solicitação de endpoint da API de administração do Atlas (v2) versionada
Registro de alterações
POSTAR

Inclui as seguintes alterações:

  • Remove as seguintes propriedades de solicitação:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adiciona a propriedade de solicitação replicationSpecs.regionConfigs

  • Remove as seguintes propriedades opcionais da resposta:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adiciona a propriedade de resposta replicationSpecs.regionConfigs

GET (all)

Inclui as seguintes alterações:

  • Remove as seguintes propriedades opcionais da resposta:

    • results.items.mongoURIWithOptions

    • results.items.providerBackupEnabled

    • results.items.mongoURIUpdated

    • results.items.srvAddress

    • results.items.replicationSpec

    • results.items.mongoURI

    • results.items.numShards

    • results.items.autoScaling

    • results.items.providerSettings

    • results.items.replicationFactor

    • results.items.replicationSpecs.regionsConfig

  • Adiciona a propriedade de resposta results.items.replicationSpecs.regionConfigs

GET (um)

Inclui as seguintes alterações:

  • Remove as seguintes propriedades opcionais da resposta:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adiciona a propriedade de resposta results.items.replicationSpecs.regionConfigs

PATCH (um)

Inclui as seguintes alterações:

  • Remove as seguintes propriedades opcionais da resposta:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adiciona a propriedade de resposta results.items.replicationSpecs.regionConfigs

  • Remove as seguintes propriedades opcionais da resposta:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adiciona a propriedade de resposta replicationSpecs.regionConfigs

Se você usar o recurso /clusters da API de administração do Atlas não versionado para criar um, obter um, obter todos, modificar um ou excluir um cluster, migre para criar um, obter um, obter todos, modificar um e excluir um endpoints no API de administração do Atlas versionada (v2) Recurso de clusters .

Se você ainda não quiser migrar para a versão 2023-02-01 , execute somente as etapas 1 e 2 do procedimento para usar a versão da API 2023-01-01 . Observe que 2023-01-01 está obsoleto.

Voltar

Versioning Overview

Próximo

Atualizações da API