api version.adoc

우선 제가 선호하는 방식은 아래와 같습니다.

1. 버전이 바뀌지 않는 한 속성 삭제는 하지 않습니다.
2. 속성을 추가만 할 때는 버전을 올리지 않습니다.

두번째가 가능하려면 모든 클라이언트에게 속성 추가에 둔감한 방식으로 응답을 파싱을 해달라고 가이드가 되어야합니다. 예를들면 Jackson에서는 mapper.configure(DeserializationConfig.Feature.FAIL_ON_UNKNOWN_PROPERTIES, false); 와 같은 옵션을 붙이는거죠.. 이게 안 되어서 속성 추가한 후 장애가 난 경우도 봤습니다. --; 통제할 수 없는 레거시가 많아서 그럴 여건이 안 되는 곳도 많으리라 생각합니다. 속성 추가만 클라이언트에서 받아준다는 전제하에서는, 하위호환성을 유지하는 작업이 그나마 해볼만해집니다. 그런데 하위호환성을 유지하면서 기능을 추가하기보다는 비슷한 API을 새롭게 추가하는 경우도 많이 봤습니다.; 그렇게 되어서 나중에 가면 중복API가 난립하게 되는 경우도 흔하기는합니다 --;

그리고 버그픽스 같은 마이너 수정도 버전을 따로 붙이고 싶은게 패키지 소프트웨어 같은 곳에서는 정석이겠지만, 서비스 API를 호출하는 클라이언트 입장에서는 그런 것까지 버전의 증가로 인지할 필요는 없지 않을까하는 생각이 듭니다. 클라이언트 입장에서는 호출과 처리 방식이 바뀌지 않는 한 '인터페이스'의 버전은 같은걸로 인지하게 하는게 좋아보입니다. 서버모듈의 버전은 implementation 버전은 될 수 있겠죠. 그런데, 서비스의 서버 모듈의 버전은 x.x.x 같은 형식보다는 날짜_순번 정도로 태깅하는 정도로 관리하는 경우가 많았던 것 같습니다. 처리 방식이 바뀌지 않더라도 Client 개발자가 참고할만한 변경은 릴리즈 노트로 공유할수도 있겠습니다.

다른 관점에서 생각해보면, Client가 버그픽스 이전의 버전을 요청한다고해서 서버에서 버그가 있는 구현을 유지할 이유는 없어보입니다. 즉 1.1.0과 1.1.1사이에 형식변화없이 버그픽스만 한 경우에 Client가 1.1.1로 요청을 해야지 버그픽스가 된 API의 구현이 호출되도록 되도록 만든다면, 클라이언트 코드까지 수정해야 버그가 픽스되는 단점이 생기게 됩니다. 그렇게 유지하는게 더 어렵기도 합니다 ^^;

포멧이 바뀌는 등 Client에서 해야할 일이 더 생기는 경우에만 버전을 올리는 전략일때는 이를 더 잘 인지시키기 위해 URL에 버전을 명시하는 전략도 괜찮은것 같습니다. Client의 사용방식이 변하지 않을때도 버전을 올리는 전략이라면 버전이 HTTP 헤더에 있는게 더 어울리는것 같습니다.

암튼 속성 추가를 같은 버전으로 받아줄수 없는 환경이라면 1.1와 같이 2단계의 버저닝도 고려해볼만해 보입니다. 다만 그럴 경우 속성이 추가될때마다 생기는 많은 버전을 동시에 서버에서는 유지해야하는 부담이 생기는것 같습니다; 그래서 저는 가급적 속성 추가는 버전을 증가시키지 않는 버전을 선호하기는합니다만 레거시의 클라이언트들의 구현을 알고 의사소통을 할 수 있는 상황이 아니라면 그 전략이 어려울것 같기는합니다.