🤔 API Versioning 은 반드시 필요할까?

Restful API 를 구현하다보면 자연스럽게 하는것중 하나가 바로 API Versioning 이지 않을까 싶습니다.

하지만 막상 이렇게 API 에 Versioning 을 해도 제대로 활용하지 못하는 경우들이 많을텐데요

API Versioning 을 언제 어떻게 사용해야하는지 명쾌하게 설명한 글이 있어 공유드립니다.

글의 내용을 간단히 정리해보면 다음과 같습니다.

📌 API Versioning 방법

• URI Versioning: "/api/v1/hello" 와 같이 URI 에 version 을 명시하는 방식

• Media Type Versioning: "Accept: application/json; v=1" 과 같이 HTTP Accept Header 에 version 을 명시하는 방식

📌 API 공개 대상에 따른 Versioning 여부

• Public API: 누구에게나 제공하는 API 이기 때문에 필요. 웹 문서 등을 통해 API 의 수명주기를 잘 관리해주어야 한다.

• Private API: 사내에서 서비스간 연동 목적으로 사용하는 API 이기 때문에 변경사항에 대해 공유가 가능하고 integration 및 품질 테스트 등을 통해 이슈를 해결할 수 있어 version 관리가 필요하진 않다.

• Partner API: API 를 제공하는 Partner 의 범위나 개발 지속성 여부에 따라 필요할 수도 있고 필요 없을 수도 있습니다.

📌 Version 업데이트는 언제 해야할까?

• API 리소스 엔드포인트의 이름이나 경로, HTTP 메서드를 바꾸거나 삭제할 경우

• 열거형(enum type)값 이름 변경 혹은 삭제

• 필드의 타입 변경(이전 타입까지 수용할 수 있는 경우는 해당하지 않음)

• 수행했던 작업이나 응답 포맷이 변경되는 경우

📌 API 버전을 새로 릴리즈할 때 진행 과정

• API 개발팀이 변경 사항을 만들고, 새 버전을 생성한 다음 테스트합니다.

• 새로운 인스턴스 및 프로덕션 파이프라인을 설정하고 배포합니다.

• 변경 내용을 문서화하고, 모든 고객에게 알립니다. 지원팀의 도움 요청에도 응해야 합니다.

• 여러 버전을 몇 달 동안 유지하며, 고객이 그사이 최신 버전으로 전환하기를 기다립니다.

• 기존 버전의 유효 기간까지 전환하지 않은 일부 고객은 결국 잃게 됩니다.

📌 API Versioning이 필요 없는 경우는?

• HTTP 메서드를 추가하는 경우

• HTTP 요청 및 응답으로 header, body에 필드를 옵션으로 추가하는 경우

• 열거형(enum type)에 허용되는 값 추가

• HTTP 리소스 URI가 확장되는 경우

• 에러 응답의 상세 메시지를 바꾸는 경우

• 에러 메시지의 아이디 적용 범위 확장

• Rate-limit과 관련된 헤더 값 조정

이에 대한 자세한 설명은 공유드린 원문 링크를 참고해주세요.

📚 원문

• https://yozm.wishket.com/magazine/detail/2554/