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 recursos. A versão atual e estável de recursos ainda inclui funcionalidades que contêm alterações não significativas. 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 a nova versão de recurso da API.

Períodos estendidos de suporte e depreciação

O Atlas substitui e depois remove as versões de recursos somente quando introduz uma nova versão de recurso de API estável. O Atlas continua a oferecer suporte à versão de recursos mais antiga 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 passam pelos estágios preview, stable, deprecated e sunset no ciclo de vida.

preview

O Atlas permite endpoints nesse estado apenas para fins de avaliação, teste e desenvolvimento. Não use os endpoints da API de administração do Atlas na visualização em seu ambiente de produção, pois os endpoints na visualização podem incluir alterações significativas e não significativas. Os endpoints da API de administração do Atlas em versão prévia também têm uma curta janela de descontinuação de aproximadamente 30 dias ou menos, após o que os endpoints podem passar para o estado stable ou deprecated.

Para usar endpoints de API na visualização, envie uma solicitação ao recurso e inclua o seguinte cabeçalho HTTP:

Accept: application/vnd.atlas.preview+json

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. Uma versão de recurso nesse estado só é atualizada com alterações não significativas.

Quando o Atlas introduz alterações significativas 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. Atlas expõe todo o legado (v1.0 e v1.5) Recursos da API de administração do Atlas em sua primeira versão em 2023-02-01 em estado estável. O Atlas oferece 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 do recurso 2023-01-01 (e equivalente ao /v1.0/clusters) está marcado como obsoleto com uma janela de descontinuação 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 suporta as 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 versões futuras de recursos obsoletos 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 enviando 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 de recursos mais recente o mais rápido possível para evitar interrupções quando as versões de recursos mais antigas forem removidas. Para saber mais sobre como migrar para uma nova versão do recurso, consulte Migrar para a API de administração do Atlas nova versão.

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 código de resposta de erro 410 Gone.

Ciclo de vida do recurso da API ilustrada

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

clique para ampliar

A figura anterior mostra o seguinte:

Pontos de extremidade daAPI

Para endpoints legado da API de administração do Atlas não versionados, o Atlas introduziu alterações novas e significativas na mesma versão. A partir da API de administração do Atlas versionada (v2), o Atlas introduz alterações significativas somente em uma nova versão de recursos. O Atlas continua a introduzir alterações não significativas 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 versionado da API de administração do Atlas (v2).

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.