버전 관리

이 주제에서는 Google API에서 사용하는 버전 관리 전략을 설명합니다. 일반적으로 이러한 전략은 모든 Google 관리 서비스에 적용됩니다.

API에 대한 이전 버전과 호환되지 않는(또는 '브레이킹') 변경이 필요한 경우가 있습니다. 이러한 종류의 변경사항으로 원래 기능에 대한 종속 항목이 있는 코드에 문제가 발생하거나 코드가 중단될 수 있습니다.

Google API는 브레이킹 체인지를 방지하기 위해 버전 관리 스키마를 사용합니다. 또한 Google API는 알파 및 베타 버전 구성요소와 같은 일부 안정성 수준에서만 사용할 수 있는 기능을 제공합니다.

안내

모든 Google API 인터페이스는 주 버전 번호제공해야 합니다. 주 버전 번호는 protobuf 패키지 끝에서 인코딩되고 REST API의 URI 경로 첫 번째 부분으로 포함됩니다. API가 필드 제거 또는 이름 변경과 같은 브레이킹 체인지를 도입한 경우 기존 사용자 코드가 갑작스럽게 중단되지 않도록 API 버전 번호를 증가해야 합니다.

API의 새 주 버전은 동일한 API의 이전 주 버전에 종속되지 않아야 합니다. API는 호출자가 API와 관련된 종속 항목과 안정성 위험을 이해한다는 가정 하에 다른 API에 종속될 있습니다. 이 시나리오에서 안정적인 API 버전은 다른 API의 공개 버전에만 종속되어야 합니다.

동일한 API의 여러 버전은 합당한 전환 기간 동안 단일 클라이언트 애플리케이션 내에서 동시에 작동할 수 있어야 합니다. 이 기간 동안 클라이언트는 새 버전으로 원활하게 전환할 수 있습니다. 이전 버전은 합당한 지원 중단 기간을 거친 후에 종료되어야 합니다.

알파 또는 베타 버전 안정성이 있는 출시 버전의 경우 API는 두 가지 전략 중 하나를 사용하여 protobuf 패키지와 URI 경로의 주 버전 번호 다음에 안정성 수준을 추가해야 합니다.

  • 채널 기반 버전 관리(권장)
  • 출시 기반 버전 관리

채널 기반 버전 관리

공개 버전 채널은 안정성 수준이 지정된 장기 출시 버전으로, 현재 위치 업데이트를 수신합니다. 주 버전의 안정성 수준당 채널은 1개입니다. 이 전략에는 알파 버전, 베타 버전, 공개 버전 등 최대 3개의 채널이 있습니다.

알파 및 베타 채널에서는 버전에 안정성 수준이 추가되어야 하지만 공개 버전 채널에서는 안정성 수준이 추가되지 않아야 합니다. 예를 들어 v1는 공개 버전 채널에 허용될 수 있지만 v1beta 또는 v1alpha는 허용되지 않습니다. 마찬가지로 각 알파 및 베타 채널에 v1beta 또는 v1alpha가 허용될 수 있지만 v1은 허용될 수 없습니다. 이러한 각 채널은 새로운 기능을 수신하고 '현재 위치' 업데이트를 수행합니다.

베타 채널 기능은 공개 버전 채널 기능의 상위 집합이어야 하고 알파 채널 기능은 베타 채널 기능의 상위 집합이어야 합니다.

지원 중단된 API 기능

API 요소(필드, 메시지, RPC)는 더 이상 사용되어서는 안 된다는 것을 나타내도록 모든 채널에 지원 중단됨으로 표시될 수 있습니다.

// A representation of a scroll.
// Books are now preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

지원 중단된 API 기능은 알파 버전에서 베타 버전으로 또는 베타 버전에서 공개 버전으로 전환되면 안 됩니다. 즉, 기능이 모든 채널에서 '사전 지원 중단'되지 않아야 합니다.

베타 채널 기능은 충분한 기간 동안(180일 권장) 지원 중단된 후에 삭제될 있습니다. 알파 채널에만 있는 기능의 경우 지원 중단은 선택사항이며 기능은 예고없이 삭제될 있습니다. 기능이 삭제되기 전에 API의 알파 채널에서 지원 중단된 경우 API는 동일한 주석을 적용해야 하며 원하는 기간을 사용할 있습니다.

출시 기반 버전 관리

개별 출시 버전은 기능이 공개 버전 채널에 통합되기 전에 제한된 기간 동안 사용할 수 있는 알파 또는 베타 출시 버전이며 공개 버전 채널에 통합되면 개별 출시 버전이 종료됩니다. 출시 기반 버전 관리 전략을 사용할 경우 API에는 각 안정성 수준에서 개별 출시 버전이 여러 개 있을 수 있습니다.

알파 및 베타 출시 버전에서는 버전에 증가하는 출시 버전 번호와 안정성 수준이 추가되어야 합니다. 예를 들면 v1beta1 또는 v1alpha5입니다. API는 문서(예: 주석)에 이러한 버전을 시간순으로 명시해야 합니다.

각 알파 또는 베타 출시 버전은 하위 호환성을 유지하도록 업데이트될 수 있습니다. 베타 출시 버전의 경우 출시 버전 번호를 증가하고 변경사항이 포함된 새 출시 버전을 게시하여 이전 버전과 호환되지 않는 업데이트를 수행해야 합니다. 예를 들어 현재 버전이 v1beta1이면 다음에 v1beta2가 출시됩니다.

알파 및 베타 출시 버전은 기능이 공개 버전 채널에 공개되면 종료되어야 합니다. 알파 출시 버전은 언제든지 종료될 수 있지만 베타 출시 버전은 사용자에게 합당한 전환 기간(180일 권장)을 제공해야 합니다.