API 버전 관리

OpenAPI | gRPC

이 페이지는 API의 버전 번호를 변경하기 위한 자세한 구성과 배포 절차를 설명합니다. 사용하는 절차는 API의 변경사항이 하위 호환되는지 여부에 따라 달라집니다.

새 API 버전에 새로운 필드 또는 메서드 추가와 같은 하위 호환 변경사항이 있는 경우, 하위 호환 변경사항을 참조하세요.
새 API에서 기존 메소드가 변경되어 고객의 클라이언트 코드가 손상될 경우, 하위 호환되지 않는 변경사항을 참조하세요.

추가 정보 및 권장사항에 대해서는 API 수명 주기 관리를 참조하세요.

하위 호환 변경사항

기존 클라이언트 코드와 하위 호환되는 API 변경사항이 있는 경우, 새 버전을 배포하기 전에 API의 부 버전 번호를 증가시키는 것이 좋습니다. Cloud Endpoints는 한 번에 API 부 버전을 한 개씩 실행하지만, Endpoints > 서비스의 그래프와 로그에는 해당 버전 번호가 표시됩니다. 배포하기 전에 부 버전 번호를 증가시키면 그래프와 로그에 라벨이 지정된 배포 기록이 제공됩니다.

부 버전 번호를 증가시키려면 다음 단계를 따르세요.

openapi.yaml에서 info.version 필드의 부 버전 번호를 증가시킵니다. 예를 들어 현재 버전이 1.1인 경우 info.version을 1.2로 설정합니다.

info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

Google Cloud CLI를 사용하여 API 구성을 배포합니다.
```
gcloud endpoints services deploy openapi.yaml
```
이전 단계에서 반환된 구성 ID를 사용하여 API 백엔드를 배포합니다. 자세한 내용은 API 백엔드 배포를 참조하세요.

하위 호환되지 않는 변경사항

고객의 클라이언트 코드를 손상시키는 API 변경사항이 있는 경우, API의 주 버전 번호를 증가시키는 것이 좋습니다. Endpoints는 API 주 버전을 동시에 여러 개 실행할 수 있습니다. 두 버전의 API를 모두 제공하면 고객이 사용할 버전을 선택하고 새 버전으로 이전할 시기를 제어할 수 있습니다.

API의 기존 버전과 새 버전을 동시에 실행하려면 다음 단계를 따르세요.

제공해야 하는 버전마다 별도의 OpenAPI 구성 파일을 만듭니다. 이 절차에서는 예시 목적으로 openapi-v1.yaml 및 openapi-v2.yaml이라는 파일 이름을 사용합니다.
openapi-v1.yaml의 내용을 openapi-v2.yaml로 복사합니다.
openapi-v1.yaml에서 다음을 구성합니다.
- info.version 필드를 기존 버전 번호로 설정합니다.
- basePath 필드는 그대로 둡니다.
예를 들면 다음과 같습니다.
```
info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"
```
openapi-v2.yaml에서 다음을 구성합니다.
- 하위 호환이 불가능한 변경사항을 적용합니다.
- info.version 필드를 새 버전 번호로 설정합니다.
- 새로운 주 버전 번호를 포함하도록 basePath 필드를 설정합니다.
- x-google-endpoints 섹션을 삭제합니다. 이 섹션은 DNS IP 주소 또는 allowCors 플래그를 지정하려는 경우에 필요합니다. 두 개의 yaml 구성 파일로 두 버전의 API를 배포할 때 하나의 파일만 x-google-endpoints를 가질 수 있지만 구성은 두 버전에 모두 적용됩니다.
예를 들면 다음과 같습니다.
```
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"
```
Google Cloud CLI를 사용하여 두 API 구성 파일을 배포합니다.
```
gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml
```
참고: Cloud Endpoints는 내부적으로 OpenAPI 구성 파일 여러 개를 구성 ID 한 개로 식별되는 단일 구성으로 변환합니다.
이전 단계에서 반환된 구성 ID를 사용하여 두 버전의 API를 모두 제공하는 단일 백엔드를 배포합니다. 자세한 내용은 API 백엔드 배포를 참조하세요.