마이크로서비스 애플리케이션은 클라이언트를 다른 서비스 팀이 이비 개발한 경우가 대부분이기 때문에 서비스 API를 변경하기가 어렵다. 서비스를 클라리언트를 모두 찾아 강제로 업그레이드시키기도 쉽지 않다. 또 요즘은 유지보수시 서버를 내리지 않기 때문에 규칙적인 단계로 서비스를 업그레이드하여 신구버전을 동시에 실행해야한다.
시맨틱 버저닝 명세는 API 버저닝에 관한 유용한 지침서이다. 여기에ㅔ는 버전 번호를 사용하고 증가시키는 규칙들이 면시되어있다. 시맨틱 버저닝은 원래 소프트웨어 패키지의 버저닝 용도로 쓰였지만, 분산 시스템의 API 버저닝에도 사용할 수 있다.
Major : 하위 호환되지 않는 변경분을 API에 적용 Minor : 하위 호환되는 변경분을 API에 적용 Patch : 하위 호환되는 오류 수정
하위 호환되는 소규모 변경
API에 뭔가를 추가하는 변경은 대부분 하위호환이 가능하다.
- 옵션 속성을 요청에 추가
- 속성을 응답에 추가
- 새 작업을 추가
이런 종류의 변경은 새 서비스에 적용해도 기존 클라이언트 역시 별 문제없이 동작한다. 이것은 견고성 원칙을 지키기 때문이다.
당신이 하는 일은 보수적으로, 다른 사람들이 하는 일은 관대하게 바라보라
요청 속성이 누락되어도 서비스는 기본값을 제공하고, 서비스가 필요한 것 보다 많은 속성을 응답하더라도 클라이언트는 무시할 수 있어야한다. 클라이언트/서비스가 견고성 원칙을 뒷받침하는 요청/응답 포맷을 사용하면 이런 과정이 매끄럽게 진행된다.
중대한 대규모 변경
경우에 따라선 매우 중요한, 기존 버전과 호환이 안 되는 변경을 API에 적용해야 할 떄가 있다. 클라이언트를 강제로 업그레이드 하는 것은 불가능하므로 일정 기간동안 서비스는 신구버전 API를 모두 지원해야한다. HTTP 기반의 REST API라면 URL에 메이저 버전 번호를 잡입할 수 있다. (**/v1/**, **/v2/**)
HTTP content negotiation을 이용해서 MIME 타입 내부에 버전 번호를 끼워넣는 방법도 있다. 버전 1.x의 주문은 클라이언트가 이렇게 요청할 수 있다.
GET /orders HTTP/1.1Accept: application/vnd.example.resource+json; version=1...
