Migrar para a nova API de administração do Atlas versionado
Nesta página
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:
Especifique o número que representa a API versionada no URL base do recurso.
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.
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.
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 .
(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:
|
GET (all) | Inclui as seguintes alterações:
|
GET (um) | Inclui as seguintes alterações:
|
PATCH (um) | Inclui as seguintes alterações:
|
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.