Visão geral da API de administração do Atlas versionado

Separação clara de alteração interruptiva e alteração não interruptiva

O Atlas introduz todos os novos recursos com alterações significativas em uma nova versão de recurso. As funcionalidades que contêm alterações não significativas continuarão a ser adicionadas à versão atual e estável do recurso. Quando o Atlas introduz uma nova versão de recurso, você pode continuar a usar a versão de recurso estável atual até que ela seja totalmente preterida enquanto você desenvolve e testa na nova versão de recurso da API .

Períodos estendidos de suporte e depreciação

O Atlas descontinua e remove as versões de recursos somente quando introduz uma nova versão de recurso de API estável. O Atlas continuará oferecendo suporte à versão mais antiga do recurso para uso em seu ambiente de produção por até 12 meses, o que lhe dá tempo para planejar e executar sua migração para a próxima versão.

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

A partir da API de administração do Atlas versionada (v2), os endpoints da API de administração do Atlas Go pelos estágios stable, deprecated e sunset no ciclo de vida.

stable

O Atlas oferece suporte a endpoints estáveis para uso em ambientes de produção. O Atlas fornece documentação, com changelogs, para todos os endpoints estáveis. A versão do recurso neste estado só será atualizada com alterações não significativas.

Quando o Atlas introduz uma alteração interruptiva nos endpoints, ele cria uma nova versão do recurso. Quando uma nova versão de recurso é lançada, o Atlas também descontinua automaticamente a versão estável atual desse recurso. O Atlas expõe todos os recursos legados (v1.0 e v1.5) da API de administração do Atlas em sua primeira versão em 2023-02-01 em estado estável. O Atlas oferecerá suporte à primeira versão (2023-01-01 e 2023-02-01) da API de administração do Atlas versionada por 24 meses após sua descontinuação. Observe que o recurso /clusters versão 2023-01-01 (e equivalente a /v1.0/clusters) está marcado como obsoleto com uma janela de dois anos.

Para usar as APIs de administração do Atlas nesse estado, envie uma solicitação para o recurso e inclua o seguinte como o cabeçalho HTTP accept:

Accept: application/vnd.atlas.<yyyy-mm-dd>+json

onde o valor de <yyyy-mm-dd> é a data de lançamento do endpoint, conforme listado na documentação e no changelog.

Atlas retorna 406 Não aceitável código de resposta de erro se sua solicitação omitir ou especificar uma versão de recurso que não existe no cabeçalho.

deprecated

O Atlas descontinua automaticamente uma versão de recurso quando o Atlas introduz uma nova versão de recurso estável. O Atlas lança uma versão nova e estável quando introduz uma alteração interruptiva em um recurso existente.

O Atlas notifica você sobre versões de recursos obsoletas no cabeçalho de resposta para solicitações. O Atlas oferecerá suporte às primeiras versões da API de administração do Atlas (2023-01-01 e 2023-02-01) por vinte e quatro meses após a descontinuação. Posteriormente, o Atlas oferece suporte a quaisquer futuras versões de recursos obsoletas para uso em seu ambiente de produção por 12 meses antes de removê-las automaticamente.

Exemplo

Veja a seguir um exemplo de cabeçalho de resposta para uma solicitação de um recurso obsoleto agendado para remoção no futuro.

Deprecation: Wed, 1 Feb 2023 00:00:00 GMT
Sunset: Sun, 1 Jun 2025 00:00:00 GMT

Você pode continuar a enviar solicitações para versões de recursos mais antigas do endpoint até que elas sejam removidas. No entanto, você deve migrar para a versão mais recente dos recursos o mais rápido possível para mitigar as interrupções quando as versões mais antigas dos recursos forem removidas. Para saber mais sobre a migração para uma nova versão de recursos, consulte Migrar para a nova API de administração do Atlas versionado.

sunset

O Atlas remove automaticamente as versões de recursos após um ano de descontinuação. Se você enviar uma solicitação para uma versão de recurso removida, o Atlas retornará o 410 Gone código de resposta de erro.

Exemplo

O exemplo a seguir ilustra o ciclo de vida de um recurso e seu impacto no controle de versão.

A figura anterior mostra o seguinte:

Data de lançamento	Detalhes da versão	Ciclo de vida da API
2023-06-01	Primeiro lançamento de um recurso na API versionada. Tem um período de depreciação de 12 meses.	#stable: application/vnd.atlas.2023-06-01+json #deprecated: none #sunset: none
01/06/2024	Nova versão de recurso criada, versões mais antigas são automaticamente descontinuadas.	#stable: application/vnd.atlas.2024-06-01+json #deprecated: application/vnd.atlas.2023-06-01+json #sunset: none
2025-01-01	Nova versão estável criada, com um curto entardecer	#stable: application/vnd.atlas.2025-01-01+json #deprecated: application/vnd.atlas.2024-12-01~preview+json application/vnd.atlas.2024-06-01+json #sunset: application/vnd.atlas.2023-06-01+json

Pontos de extremidade daAPI

Para endpoints de API de administração do Atlas legado não versionados, o Atlas introduziu uma alteração interruptiva e novas na mesma versão. A partir da API de administração do Atlas versionada (v2), o Atlas introduz alterações significativas apenas em uma nova versão do recurso. O Atlas continuará a introduzir alterações não interrompidas na versão stable existente. Use a data de lançamento de um recurso para enviar uma solicitação para uma versão específica de um endpoint da API de administração do Atlas (v2) versionado.

A tabela a seguir mostra as versões de ponto de conexão da API legado, se a versão tem um ponto de conexão da API de administração do Atlas (v2) com versão correspondente e a data de lançamento do recurso de API de administração do Atlas com versão (v2). Observe que um equivalente de v1.0 na API de administração do Atlas não versionada é representado por 2023-01-01 na API de administração do Atlas versionada, que agora está obsoleta.