버전이 지정된 Atlas 관리 API 개요
Atlas provides a versioned Atlas Administration API for a predictable and consistent experience when handling API changes. The API versioning happens at the individual API resource-level. So, you need to take action if and when Atlas deprecates the resources that you are utilizing. You don't need to take any action if you haven't implemented a resource for which Atlas released a new version. This allows you to plan for new features, prevent breaking changes, and ensure a smooth integration process while maintaining stability and minimizing disruptions in your production environment.
버전이 지정된 Atlas 관리 API의 이점
새로운 버전의 Atlas 관리 API는 프로그래밍 방식으로 Atlas에 액세스할 때 전반적인 환경이 크게 향상되었습니다. 버전이 지정된 Atlas 관리 API는 다음을 제공합니다.
호환성이 손상되는 변경과 호환성이 손상되지 않는 변경의 명확한 구분
Atlas introduces all new features with breaking changes in a new resource version. The current, stable resource version still includes features that contain non-breaking changes. When Atlas introduces a new resource version, you can continue to use the current stable resource version until it is fully deprecated while you develop and test on the new API resource version.
지원 및 사용 중단 기간 연장
Atlas deprecates and then removes resource versions only when it introduces a new stable API resource version. Atlas continues to support the older resource version for use in your production environment for up to twelve months, which provides you with time to plan and execute your migration to the next version.
버전 관리 스키마
버전이 지정된 새로운 Atlas 관리 API(v2)부터 Atlas 관리 API 버전은 Atlas 관리 API 리소스의 수명 주기를 기반으로 합니다.
버전이 지정된 Atlas 관리 API 수명 주기
버전이 지정된 Atlas 관리 API(v2)부터 Atlas 관리 API 엔드포인트는 수명 주기에서 stable, deprecated, sunset 단계를 Go합니다.
중요
이 단계는 버전이 지정된 리소스의 Atlas 관리 API(v2)에 있는 Atlas 관리 API 엔드포인트에만 적용됩니다. 이러한 단계는 v1.0 또는 v1.5 리소스의 Atlas 관리 API 엔드포인트에 영향을 주지 않습니다. Atlas는 2023-02-01 의 첫 번째 릴리스에서 모든 레거시(v1.0 및 v1.5) Atlas 관리 API 리소스를 stable 상태로 노출합니다.
stableAtlas supports stable endpoints for use in production environments. Atlas provides documentation, with changelogs, for all stable endpoints. A resource version in this state only updates with non-breaking changes.
When Atlas introduces breaking changes to endpoints, it creates a new resource version. When a new resource version is released, Atlas also automatically deprecates the current stable version of that resource. Atlas exposes all legacy (v1.0 and v1.5) Atlas Administration API resources in its first release on
2023-02-01in stable state. Atlas supports the first release (2023-01-01 and 2023-02-01) of the versioned Atlas Administration API for 24 months after its deprecation. Note that the/clustersresource version 2023-01-01 (and equivalent of/v1.0/clusters) resource is marked as deprecated with two years deprecation window.이 상태에서 Atlas 관리 API를 사용하려면 리소스에 요청을 보내고 다음을 HTTP 수락 헤더로 포함하십시오.
Accept: application/vnd.atlas.<yyyy-mm-dd>+json 여기서
<yyyy-mm-dd>값은 문서 및 변경 로그에 나열된 엔드포인트의 릴리스 날짜입니다.Atlas 가 을(를)406 반환할 수 없음 요청 에서 헤더에 존재하지 않는 리소스 버전을 생략하거나 지정하는 경우 오류 응답 코드입니다.
deprecatedAtlas는 새롭고 안정적인 리소스 버전을 도입할 때 리소스 버전을 자동으로 사용하지 않습니다. Atlas는 기존 리소스에 호환성이 손상되는 변경이 도입될 때 새롭고 안정적인 버전을 릴리스합니다.
Atlas notifies you about deprecated resource versions in the response header for requests. Atlas supports the first releases of the Atlas Administration API (2023-01-01 and 2023-02-01) for twenty-four months after deprecation. Subsequently, Atlas supports any future deprecated resource versions for use in your production environment for twelve months before automatically removing them.
예시
다음은 향후 제거될 예정인 사용 중단된 리소스에 대한 요청에 대한 응답 헤더의 예시입니다.
Deprecation: Wed, 1 Feb 2023 00:00:00 GMT Sunset: Sun, 1 Jun 2025 00:00:00 GMT You can continue to send requests to older resource versions of the endpoint until they are removed. However, you should migrate to the latest resource version as soon as possible to avoid disruptions when older resource versions are removed. To learn more about migrating to a new resource version, see 새 버전이 지정된 Atlas 관리 API로 마이그레이션.
sunsetAtlas는 1년 간의 지원 중단 이후 리소스 버전을 자동으로 제거합니다. 제거된 리소스 버전에 요청을 보내면 Atlas는 Gone 을 반환합니다.410 오류 응답 코드.
예시
다음 예는 리소스의 수명 주기와 리소스가 버전 관리에 미치는 영향을 보여줍니다.
앞의 그림은 다음을 보여줍니다.
출시일 | 릴리스 세부 정보 | API 라이프사이클 |
2023-06-01 | 버전이 지정된 API의 첫 번째 리소스 릴리스입니다. 사용 중단 기간은 12개월입니다. |
|
2024-06-01 | 새 리소스 버전이 생성되었으며, 이전 버전은 자동으로 더 이상 사용되지 않습니다. |
|
2025-01-01 | 짧은 선셋이 포함된 새로운 스테이블 버전이 생성되었습니다. |
|
API 엔드포인트
For legacy unversioned Atlas Administration API endpoints, Atlas
introduced new and breaking changes in the same version. Starting in
versioned Atlas Administration API (v2), Atlas introduces breaking
changes only in a new resurce version. Atlas continues to
introduce non-breaking changes to existing stable version. Use the
release date of a resource to submit a request to a specific version of
a versioned Atlas Administration API (v2) endpoint.
다음 표에는 레거시 API 엔드포인트 버전, 버전에 해당 버전이 지정된 Atlas 관리 API(v2) 엔드포인트가 있는지 여부, 버전이 지정된 Atlas 관리 API(v2) 리소스의 릴리스 날짜가 나와 있습니다. 버전이 없는 Atlas 관리 API에서 v1.0에 해당하는 버전은 현재 더 이상 사용되지 않는 버전이 있는 Atlas 관리 API에서 2023-01-01 로 표시됩니다.
버전 번호 | v2에서 지원되나요? | v2 리소스 버전( yyyy-mm-dd 형식) |
|---|---|---|
| √ |
|
| √ |
|
다음 단계
다양한 버전의 모든 API 변경 사항을 확인할 수 있는 API 변경 로그 를 검토합니다.
모든 안정적인 리소스 버전과 더 이상 사용되지 않는 리소스 버전에 대한 정보가 포함된 API 사양 을 검토하세요.
마이그레이션 가이드 의 단계에 따라 현재 버전이 없는 Atlas 관리 API에서 버전이 지정된 새 Atlas 관리 API로 마이그레이션합니다.