API 버저닝의 필요성

이번 포스팅에서는 API 버저닝과 관련하여 겪어온 일과 최근 LAH에서 있었던 일화를 소개하려고 합니다.

API 버저닝은 말 그대로 API endpoint에 버전 정보를 포함하는 경우를 말합니다. 다양한 형태가 될 수 있겠죠.
HOST/v1/hello, HOST/v2/hello와 같이 URL에 포함하는 경우도 있고, 요청 헤더에 포함하는 경우도 있습니다.
경우에 따라 Query Parameter로 전달하는 경우도 있습니다.

과거 개인적으로 오픈 소스를 보거나, 타 API 서비스를 이용할 때 간혹 API에 버전이 포함되어 있는 경우가 있었습니다.
무엇보다도 REST API를 만드는 프레임워크(예를 들면 DRF나 NestJS 등)에도 꼭 Versioning이 있습니다.
그때마다 이건 왜 필요할까? 뭐 굳이 버저닝을 할 필요가 있을까? 라고, 생각했었습니다.

경험이 부족하다 보니 생각이 짧았었죠.
회원가입 API를 예로 들면, a 프로세스로 회원가입 기능을 만들었습니다. 그러다 서비스가 업데이트 되어서 b 프로세스로 회원가입을 하게 되었습니다.
그러면 당연히 서비스가 업데이트 되는 것이기 때문에 a 프로세스는 필요 없어지고 b 프로세스로 덮어쓰면 되는 것으로 생각했습니다.
왜냐하면 오픈 API를 제공하는 형태가 아니기 때문에 그렇게 생각했었죠.
(사실 이 관점으로 쉽게 생각하면 그렇게 틀린 것이 아닐 수도 있습니다.)

최근에 비디어스는 유료 기능을 개발하면서 서비스의 전반적인 개편이 있었습니다. 유료 모델이 추가되다 보니, 일부 DB 스키마 변경도 필요하게 되었고,
기존 API도 꽤 많이 수정되었습니다. 그렇게 개발 서버에서 테스트를 마치고, 웹과 앱 개발이 거의 마무리되어 갈 때쯤 배포 계획을 세웠습니다.
앱 심사를 언제 넣고, 웹 배포를 어떻게 맞출지 계획을 하는데 뭔가 문제가 있는 것을 그제야 알게 되었습니다.

백엔드의 API가 전부 수정되어 있다 보니, 웹 프론트엔드도, 앱도 최신버전이 아니면 동작하지 않는 것이었습니다.
웹 프론트엔드는 바로 배포하면 문제없지만 앱은 사용자들이 바로 업데이트를 안 할 수도 있다는 점이었습니다.
다행히 앱에 사용자의 업데이트를 강제하는 기능이 들어가 있어서 업데이트를 유도하면 문제없겠지만, 가장 큰 문제는 심사였습니다.

앱을 심사 받는 동안 앱이 정상적으로 동작하기 위해서는 백엔드가 최신 버전이어야 하는데, 백엔드를 최신 버전으로 구성하게 되면 기존 앱이 동작하지 않게 됩니다.
이 상황을 직면하자마자 API의 버저닝이 생각났습니다.
“아, 이래서 API를 버저닝해야 하는구나”

버저닝을 해야 하는 이유야 많겠지만, 직접 문제를 만나면서 배우게 되었습니다.

그 이후로 비디어스 배포는 어떻게 되었을까요? 금요일~토요일 동안 이런 이슈를 우회하고자 했던 환경 구성 중 휴먼 에러로 회원가입이 안되는 비상이 발생했지만,
그래도 앱 심사는 잘 마무리되었고, 월요일에 무사히 웹과 앱을 배포할 수 있었습니다.

우회 과정에 대한 힌트를 살짝 드리자면, 같은 DB를 바라보는 백엔드v1, 백엔드v2를 띄우고 앱은 v2를 바라보도록 했습니다.
그리고 앱과 웹 모두 v2로 안정적으로 전환이 완료되면, 추가로 배포한 백엔드v2를 종료시킬 예정입니다.
그렇게 우여곡절 끝에 비디어스의 배포가 완료되었습니다.

이제 언젠가 이런 일이 또 발생하지 않아야 하므로, 개발팀에 또 숙제가 생겼습니다. 파이팅.

---