API 버전 관리

Recommanded Free YOUTUBE Lecture: <% selectedImage[1] %>

yundream
2022-10-26
2022-10-15
4316

## 개요
API 버전관리가 점점 힘들어지고 있다. API는 더 이상 쓸모가 없어 폐기 될때까지 계속적인 수정, 업데이트, 기능 추가가 발생한다. 이 기능은 클라이언트 애플리케이션의 작동과 품질에 영향을 주기 때문에, 각 API의 변경 내용을 추적하고 관리 할 수 있어야 한다.

일반적으로 API의 버전을 이용해서 추적 관리한다. 문제는 클라우드환경에서 MSA 도입이 늘어나면서 API 버전관리가 힘들어지고 있다는 점이다.

API 버전 관리는 앞으로도 힘들어지겠지만 몇 가지 관리 방법이 있으니 이를 살펴보도록 하자.

## API는 계약이다.
먼저 API는 계약이라는 점을 언급해야 할 것 같다. 이 계약의 당사자는 (주로 백앤드)개발자 와 API 사용자 혹은 애플리케이션 개발자다. 계약의 당사자는 때때로 귀찮아서, 시간이 부족해서 계약서를 대충 작성하고 넘어가고는 한다. 하지만 결국 미래에 부채로 다가오게 되며, 이때문에 꼼꼼하게 계약서를 작성한다.

따라서 API 문서를 제대로 작성하지 않으면 나중에 부채로 돌아온다. 기술 부채라는 것은 코드의 형태로만 쌓이는게 아니다.

## API 문서의 작성
그러므로 개발자는 계약서를 작성한다는 자세로 API 문서를 만들어야 한다.
  * 버전 : API의 버전
  * 사양 : API의 목적과 API의 모든 기능에 대한 세부 정보를 나열해야 한다. 
  * 요청 : API의 목적을 달성하기 위해서 보내야 하는 데이터, 데이터 포맷을 작성해야 한다.
  * 응답 : API의 처리 결과 응답하는 데이터와 데이터의 포맷을 작성한다. 여기에는 성공 뿐만 아니라 실패 경우에 대한 내용이 모두 들어간다.

API 사용자는 API 문서에 따라서 개발 했을 때, 어떤 결과가 나타날지를 문서를 통해서 예측하고 애플리케이션 개발에 반영 하게 된다.

대부분의 (개발자를 포함)사람들이 문서화를 싫어하기 때문에, API 문서를 잘 작성하는 것은 차별화된 능력이 될 수 있다.(API 문서를 잘 작성하는 사람들은 다른 문서들도 잘 작성한다.)

## Swagger를 이용한 API 문서 관리
![](https://static1.smartbear.co/swagger/media/images/fast-standardized-design-swagger-screenshot.png)
Swagger는 널리 사용하는 API 문서 관리 툴이다.

Swagger는 YAML 혹은 JSON으로 API의 사양을 관리 할 수 있다. 이 사양은 아래와 같은 정보들을 넣을 수 있다.
* API가 수행하는 작업
* API의 매개변수와 리턴 값들
* API에 인증/승인 과정이 필요한지
* 약관, 연락처 정보, API 사용 라이센스
* 테스트 정보들
* 요청 / 응답에 대한 데이터 모델

API 개발자는 Swagger 사용을 수동으로 작성하거나 주석을 통해서 자동생성되도록 할 수 있다. 게다가 사용하기 쉬운 웹 기반 및 IDE와 통합된 플러그인등을 제공하고 있어서 관리하기도 쉽다.

* [Swagger Editor](https://editor.swagger.io/) : 온라인 상에서 API를 사양을 개발 할 수 있다.
* [VS code swagger extension](https://github.com/arjun-g/vs-swagger-viewer)
![VS code swagger extension](https://webhookrelay.com/images/blog/openapi-redoc-guide/swagger-vscode.png)
## 버전관리
API는 버그수정, 기능추가, 기능변경 등으로 계속해서 변한다. API 사용자는 버전 번호를 이용해서 이러한 변화를 확인하고 그에 맞게 대응 한다.

API 버전을 관리 할 때 아래 몇 개의 원칙을 고려해야 한다.

### 포스텔의 법칙
포스텔의 법칙은 견고함의 원칙이라고도 부르며 다양성과 복잡성에 대처하는 인간 중심 경험을 디자인하는데 도움을 준다. 핵심은
> 자신이 행하는 일은 엄격하게, 남의 것을 받아들일 때는 너그럽게

이다.

이에 따르면 API 개발자는 API 사용자에게 요청하는 정보의 양을 보수적으로 책정해야 한다. 그렇지 않으면 사용자가 이를 인지하고 분석하는데 많은 노력이 들어가게 되고, 실수할 확률이 높아진다.
  * 응답은 보수적으로 변경 한다. : 자신이 행하는 일은 엄격하게
  * API 사용자의 요청을 자유롭게 수락 : 남의 것을 받아들일 때는 너그럽게

이러한 사고 방식을 기반으로 아래와 같이 API 버전을 관리 할 수 있다.
  * Major Change
  * Minor Change 
  * Patch updates

이렇게하면 API 사용자는 최소한의 노력으로, 애플리케이션에 대한 의사결정을 할 수 있다.

### 점진적인 변화
API에서 극적인 변화가 나타나는 것은 좋지 않다. 새로운 버전의 API는 점진적으로 변화를 주면서 **진화** 시켜나가는게 좋다. 때때로 개발자들은 이전 API에 대해서 "저것은 레거시다. 완전히 새로 바꾸자"라는 입장을 가지기도 한다. 다시 말하지만 API는 계약이다. 계약은 점진적으로 수정해야 한다.

API 사용자가 영향을 받는 요소는 아래와 같다.
  * Schemas : API 전체를 통틀어서 일관된 형태를 취해야 한다.
  * Mental models : 사용자는 시스템의 이미지를 통해서 제품과 상호 작용한다. API의 이미지와 API를 사용하는 애플리케이션의 이미지가 일치하지 않으면 사용자는 API를 사용하기 어렵다고 느낄 것이다.
  * Expectations : 기대한 대로 작동 할 것이라는 것을 믿을 수 있어야 한다.

API 개발자가 할 수 있는 일은 다음과 같다.
  * API 사용자는 기존의 기대와 일치하도록 해야 한다.
  * 새로운 API는 제품 전반을 가로지르는 Mental models에 따라서 작동 하도록 개발한다.

### Semantic version 관리
![Semantic Version](https://docs.google.com/drawings/d/e/2PACX-1vR2Rr-dH2qHMEAJkMCqFpu-cPlG6wADfjfcJ4z4hsrA0zk5uSUpgEEV-0x3y_0FhBQIeXS5hFsn9BKe/pub?w=918&h=574)
시맨틱 버전(Semantic version 혹은 SemVer)은 개발자가 기존 API와의 연속성을 해치지 않으면서 패치, 마이너 변경을 관리 할 수 있도록 도와준다. 다음은 시맨틱 버전의 주요 특징이다. 
  1. 버전명은 **X.Y.Z** 형태를 가진다. X, Y, Z는 양의 정수이다. ex) 1.1.2
  2. X는 Major version, Y는 Minor version, Z는 Patch version이다. 각 요소는 1씩 차례로 증가한다. ex) 1.1.2 -> 1.1.3
#### Patch version
이 버전에서는 API의 기능 변경이 없는 API 변경사항이다. 버그가 수정되었을 경우 주로 사용한다. 완벽한 하위 호환을 보장한다. API 사용자는 애플리케이션을 수정할 필요가 거의 없으며, 패치내용을 참고만 하는 경우가 대부분이다.

#### Minor Version
새로운 필드가 추가 되는 등의 사소한 변경사항이다. 애플리케이션 수정은 선택사항이다. 코드변경은 새로운 기능을 사용하기 위해서만 필요하다. 즉 하위 호환성을 보장한다.

### Major Version
API의 많은 내용이 변경되었으며, 애플리케이션의 변경이 필요하다. 해당 API를 사용하는 코드를 새로 개발해야하며 테스트 하는데 많은 시간이 필요하다.

### Semantic version 을 이용한 API 관리 전략
이커머스 웹 애플리케이션을 개발하고 있다고 가정해보자. 백앤드 개발자는 카트(cart) 기능을 제공하는 RestFul API를 제공해야 한다. 이 ResTful API는 아래와 같은 정보를 포함 할 것이다.

1. 도메인
  1. 서브도메인
  1. 버전
  1. 리소스

예를들어 cart에 물건을 담기 위한 API는 아래와 같을 것이다.
```
POST /ecommerce/v2/cart

{
    "nventory_id": 4321,
    "quantity": 1
}
```
서비스 도메인이 shop.joinc.co.kr 이라면 "https://shop.joinc.co.kr/ecommerce/v2/cart"을 호출하게 된다.

**basePath**에 버전을 명시하면, 동일한 기능이 2개의 버전을 가지더라도 애플리케이션 개발자는 이전 버전을 계속 사용 할 수 있기때문에 개발 편의성을 높일 수 있다.

하지만 basePath에는 minor version과 patch version을 추가하는 건 좋은 생각이 아니다. 요즘에는 기능을 시장에 빠르게 출시하는게 경쟁력이기 때문에 자주 변경될 수 있다. Minor와 patch가 basePath에 들어간다면 애플리케이션 통합에 어려움을 겪게 될 것이다.

API 개발자는 major 버전을 유지하는 한 하위 호환성이 유지도록 신경써서 API를 개발해야 한다.

### Major 변경이 생길 경우
Cart API에 Major 변경사항이 발생했다고 가정해보자. 이 경우 API는 아래와 같을 것이다.
```
POST /ecommerce/v2/cart
```
basePath에서 버전명만 변경된다. 이 cart api를 사용하기 위해서는 클라이언트 변경이 필요하다.

### 이전 Major 버전의 유지
새로운 Major version이 출시되었다고 해서 기존 API를 제거하면 안될 것이다. 당분간은 두 개 버전의 API를 함께 유지할 필요가 있다.

하지만 두개 버전의 API를 유지하는데에는 많은 비용이 들어가기 때문에 API 사용자가 새로운 버전으로 마이그레이션 하도록 유도해야 할 것이다.

API 개발자는 API 마이그레이션 일정에 대한 정책을 사전에 명시해서 사용 중단 정책을 수행해야 한다.

### 시험판 및 빌드에 대한 정보
때때로 테스트 목적으로 일부 사용자에게 비공식적으로 새로운 기능을 출시하기를 원한다. 시험판이라고도 하는데, 이러한 정보들은 **하이픈(-)** 을 이용하여 설명할 수 있다.

![SemVer](https://docs.google.com/drawings/d/e/2PACX-1vRFxw6o6IUU9Gj2ihfe-Wk_58OaTjRhwZJWpEm2dprSNojTVhGEWkmAQBc4KUMm6tfzIlEf9Xwk1OBK/pub?w=688&h=234)

위 버전에서는 이 API가 2.13.0 API를 기준으로 하는 alpha 테스트 버전이라는 정보를 포함하고 있다. 2.13.0 과 호환되기는 하지만 alpha 버전이기 때문에 안정적이지 않을 수 있으며, 일부 호환성에 문제가 발생할 수 있다.

일부 개발팀은 빌드를 만든 사람(혹은 팀), 빌드시간, git hash tag 같은 **빌드 메타데이터**를 기록하고 싶을 때가 있다. 이런 정보들은 **플러스(+)** 기호 다음에 추가할 수 있다.

## SemVer의 인기 이유
SemBer는 아래와 같은 이유로 최근 인기를 끌고 있다.
* 이해하고 사용하기 쉽다.
* 버전 히스토리를 비교하는 것으로 각 버전별 주요, 마이너한 변경사항을 즉각 확인 할 수 있다.
* 변경사항을 쉽게 추적할 수 있다.
* Major, Minor, Patch 변경 여부사항을 확인하여 패키지 업데이트시 감수해야 할 위험요소를 즉각적으로 판단할 수 있다. 예를 들어 패치변경 사항은 현재 구현이 중단되지 않으면서 지속적인 개선이 가능하다는 것을 확신 할 수 있다.
* 소위 말하는 종속성의 지옥을 피할 수 있도록 도와준다. SemVer는 종속성 관리를 위한 명확한 버전관리 방안을 제공한다.

## 결론
SemVer는 유일한 버전관리 체계가 아니다. CalVer, Python 버전관리, Sprint 프로젝트 버전관리 등 다양한 체계들이 있다. 하지만 오픈 소스 프로젝트에서 널리 사용하고 있다. 예를 들어 가장 거대한 오픈 소스 중 하나인 리눅스 커널도 SemVer를 기반으로 버전을 관리하고 있다.
```
$ uname -r
4.14.123-111.109.amzn2.x86_64
```
수많은 사람이 공동개발하는 리눅스 커널도 사용하고 있는 믿을 수 있는 버전 관리 체계다.

Search For:

BY TAGS

Recent Posts

Archive Posts

Tags

About

Get in Touch

Categories