API Versioning
백오피스 프로젝트의 중간피드백에서 API Versioning에 대한 요구사항이 있었다.
버전, 한국말로 수정판이라는 말은 책에서는 많이 들어봤다.
하지만 API의 version이라는 것은 생소하다. 이것은 무엇이고 왜 쓰는 것일까?
Version 이란
"버전(Version)"은 소프트웨어 개발에서 특정 코드나 소프트웨어의 특정 상태를 나타내는 식별자를 의미한다. 버전은 주로 변경된 내용, 새로운 기능, 버그 수정 등과 같은 업데이트를 추적하고 관리하기 위해 사용하며, 여러 가지 형태의 소프트웨어 버전이 있다.
version의 형태
-
숫자 형태 : "메이저 버전.마이너 버전.빌드 번호"와 같은 형식으로 표현. 메이저 버전은 큰 변경이 있을 때 증가하고, 마이너 버전은 작은 변경이나 기능 추가가 있을 때 증가하며, 빌드 번호는 보통 각 빌드마다 증가한다.
-
릴리즈 형태 : "알파(Alpha)", "베타(Beta)", "릴리즈 후보(RC, Release Candidate)" 등과 같이 개발 단계를 나타내는 단어나 약어를 사용. 알파 버전은 초기 개발 단계를 나타내며, 베타 버전은 테스트 중인 개발 단계를 나타낸다. 릴리즈 후보는 공식 릴리즈 전 마지막 테스트를 거친 버전이다.
-
일련 번호(시퀀스 번호) 형태 : 간단히 연속된 숫자를 사용하여 각 버전을 식별. 새로운 버전이 나올 때마다 번호를 증가시키는 방식.
Version의 사용 이유
-
업데이트 추적: 버전을 사용하면 특정 시점의 소프트웨어 상태를 식별 가능. 이것으로 사용자나 개발자는 어떤 변경 사항이 있었는지, 언제 업데이트를 해야 하는지 등을 파악할 수 있다.
-
호환성 유지: 버전을 통해 서로 다른 버전의 라이브러리나 프로그램 간의 호환성을 확인하고 유지할 수 있다.
-
버그 수정 및 기능 개선: 버전은 버그를 수정하거나 새로운 기능을 추가할 때, 어떤 변화가 있었는지를 명시하는 데 사용된다.
API Versioning 전략
출처: 선호하지 않는 버저닝 전략
-
도메인 전략과 쿼리 파라미터 전략은 가장 선호하지 않는 전략이다.
도메인 버저닝 전략은 작은 변경에도 도메인이라는 비교적 큰 단위의 변경이 필요하며, 쿼리 파라미터 버저닝 전략은 패스와 파라미터의 역할을 침범할 수 있다. -
커스텀 헤드 전략과 콘텐츠 네고시에이션은 좀 더 RESTful 한 설계가 가능하기에 좋아 보인다.
하지만 컨슈머의 사용이 어렵고, 무엇보다 변경을 인지하는 것이 어렵다.
그렇더라도 내부용으로만 사용된다면 충분히 좋은 선택이라고 생각합니다. -
컨슈머의 설정 전략은 컨슈머 친화적이지만 프로바이더에서 고려할 것이 너무 많다.
경로 버저닝 전략
위의 것들을 고려했을 때, 경로 버저닝 전략이 가장 직관적이고 컨슈머와 프로바이더 모두가 만족 할 수 있는 방식이라고 생각하였다. 따라서 우리 프로젝트는 경로 버저닝 전략을 이용하여 http://localhost:8080/api/** 라는 주소 대신, http://localhost:8080/v1/** 이라는 주소를 갖게 되었다.
그동안 버전이란 것을 모르고 살아서 그렇지, 웹을 돌아다니다보니 버전 정보가 url에 포함되어 있는 경우도 보인다.
역시 알아야 보이는가보다! 오늘도 세상을 보는 눈이 넓어졌다~
아직까지 만든 팀프로젝트는 v1으로, 앞으로 수정 할 일이 있다면 v2로 해야겠다!
(아직 배포는 안해봤지만 설레발)
관련 포스팅
