API 버저닝

API 는 프로그램끼리 주고받기로 약속한 창구입니다. 창구를 한번 열어 두면 남의 회사 개발자가 그 약속을 보고 자기 코드를 짭니다. 여기서 문제가 생깁니다. 창구를 연 쪽은 자기 코드를 고치는 기분으로 응답 항목 하나의 이름을 바꾸지만, 그 항목을 읽던 바깥의 코드는 그 순간 멈춥니다.

한 결제 서비스가 응답에서 user_name 을 name 으로 바꾸고 공지를 올렸다고 해 봅시다. 공지를 못 본 회사들의 주문 화면에서 구매자 이름이 빈칸으로 찍히기 시작하고, 원인을 찾는 데 하루가 갑니다. 고친 쪽은 이름 하나 다듬었을 뿐이고, 깨진 쪽은 자기가 아무것도 건드리지 않았는데 서비스가 멈춥니다.

그래서 한동안은 규격을 아예 고치지 않는 쪽으로 버텼습니다. 첫 설계가 어색해도 그대로 두고, 새 기능은 항목을 덧붙이는 식으로만 넣었습니다. 몇 년이 지나면 쓰지 않는 항목과 뜻이 어긋난 이름이 잔뜩 쌓여 창구 하나를 읽는 데 설명이 필요해집니다.

API 버저닝은 이 둘 사이에서 나온 절충입니다. 규격을 고치되 옛 규격을 지우지 않고, 두 판을 한동안 나란히 열어 둡니다. 쓰던 쪽은 자기 일정에 맞춰 옮겨 가고, 여는 쪽은 옛 판을 언제 닫을지 미리 알립니다.

바뀌는 내용이 정말 판을 나눌 만한 변경인지부터 가릅니다. 여기서 대부분이 걸러집니다.

1. 변경의 성격을 판정합니다. 응답에 항목을 새로 더하는 것은 옛 코드가 그 항목을 그냥 무시하므로 판을 나눌 일이 아닙니다. 항목을 없애거나 이름을 바꾸거나 입력값을 새로 필수로 요구하는 것은 브레이킹 체인지이고, 여기서부터 판을 나눕니다.
2. 판을 구분할 자리를 정합니다. 주소에 넣는 방식이 가장 흔합니다. /v1/documents 와 /v2/documents 처럼 경로에 판 번호가 보이면 무엇을 부르는지 눈으로 확인됩니다. 요청 헤더에 판 번호를 싣는 방식도 있는데, 주소는 깔끔해지지만 무슨 판을 부르는지 로그를 열어야 압니다.
3. 새 판을 올리고 옛 판을 그대로 둡니다. 두 판이 같은 데이터를 보되 응답 모양만 다르게 만드는 것이 보통이라, 안쪽 로직은 하나로 두고 바깥으로 내보내는 부분만 둘로 나눕니다.
4. 옛 판에 디프리케이션 표시를 답니다. 곧 없앨 예정이라고 미리 알리는 상태를 말합니다. 문서에 적는 것으로 끝내지 말고, 옛 판 응답에 종료 예정일을 담은 헤더를 같이 실어 보냅니다. 문서를 다시 읽는 개발자는 드물지만 응답은 매일 봅니다.
5. 옮겨 간 비율을 셉니다. 판별로 요청 수를 따로 세면 오늘 옛 판을 부르는 곳이 몇 군데인지, 그게 누구인지 보입니다. 큰 고객이 남아 있으면 따로 연락합니다.
6. 옛 판을 닫습니다. 공지한 날짜에 한 번에 끄는 대신, 하루 한두 시간씩 미리 꺼 보는 방법을 씁니다. 아직 남은 곳이 그날 바로 연락해 옵니다.

3번과 6번 사이가 보통 6개월에서 1년입니다. 이 기간을 처음 공지할 때 못 박아 두지 않으면 옛 판은 영원히 남습니다.

밖으로 공개한 창구에 맞는 방법입니다. 누가 쓰는지 명단을 알 수 없고, 쓰는 쪽의 배포 일정을 이쪽에서 정할 수 없을 때 판을 나눠 시간을 법니다.

반대로 한 회사 안에서 서비스끼리 부르는 창구에는 과한 장치입니다. 부르는 쪽 코드를 이쪽에서 같이 고칠 수 있으면 판을 나누는 대신 양쪽을 같은 날 배포하는 편이 빠릅니다. 사내 창구까지 전부 판을 나누면 유지할 코드만 두 배가 됩니다.

한계는 값입니다. 판이 둘이면 고칠 곳도 둘이고, 보안 문제가 하나 나오면 두 판에 같은 수정을 넣어야 합니다. 판이 셋을 넘어가면 어느 판에 무엇이 들어갔는지 아무도 외우지 못하는 상태가 됩니다. 그래서 동시에 열어 두는 판은 둘까지로 잡고, 새 판을 열 때 그 앞판을 닫는 일정을 같이 잡습니다.

판을 나누는 것 자체가 목적이 되는 것도 경계할 대목입니다. 하위 호환성을 지키는 설계로 해결되는 변경이라면 판을 나누지 않는 편이 낫습니다.

"이거 응답 항목 이름만 바꾸는 건데 v2 까지 열어야 하나요?"

이름 변경이 바깥 코드를 깨뜨리는 변경인지, 판을 나눌 만한 값인지를 함께 판단하자는 물음입니다.

"v1 종료일을 3월로 공지했는데 아직 트래픽의 12퍼센트가 v1이에요."

공지만으로는 안 옮겨 간다는 뜻이고, 남은 곳에 개별 연락이 필요하다는 신호입니다.

"이번 변경은 항목 추가라서 버저닝 없이 그냥 나갑니다."

옛 코드가 새 항목을 무시하고 지나가므로 판을 나눌 필요가 없다는 판단입니다.

페이지덱은 다른 협업 도구와 문서를 주고받는 창구를 공개해 두고 있습니다. 태오가 문서 응답에서 작성자 정보를 이름 한 줄 대신 이름과 이메일과 프로필 주소가 든 묶음으로 바꾸려 했을 때, 지현이 먼저 물은 것은 지금 그 창구를 부르는 곳이 몇 군데냐는 것이었습니다. 37곳이었고 그중 넷이 유료 기업 고객이었습니다.

팀은 /v2/ 를 새로 열고 v1 을 그대로 두기로 했습니다. v1 응답에는 9월 30일 종료 예정이라는 표시를 실었고, 매주 판별 요청 수를 확인했습니다. 8월 말에 v1 을 부르는 곳이 셋 남았을 때 수아가 그 셋에 직접 연락해 일정을 받아 왔습니다. 종료는 예정대로 됐고, 그날 문의는 한 건도 오지 않았습니다.

판을 나눠 뒀으니 새 판은 마음대로 고쳐도 된다고 생각하기 쉽습니다. v2 는 방금 연 판이고 쓰는 곳도 적으니 그렇게 보입니다. 하지만 누군가 v2 에 연동을 붙이는 순간 v2 도 옛 판과 같은 처지가 됩니다. 이 상태로 v2 를 계속 손보면 같은 판 번호를 달고 규격이 조금씩 달라져, 쓰는 쪽은 판 번호를 봐도 무엇을 받게 될지 모르게 됩니다. 판 번호는 그 판의 규격이 더 안 바뀐다는 약속일 때만 뜻이 있습니다.

판을 새로 열면 옛 판은 알아서 비어 간다는 것도 흔한 오해입니다. 새 판에 좋은 기능이 있으니 자연히 옮겨 갈 것처럼 보입니다. 실제로는 잘 돌아가는 연동을 굳이 손보려는 개발자가 없어서, 종료일을 못 박지 않으면 몇 년이 지나도 옛 판 요청이 그대로 남습니다. 그 사이 두 판을 다 유지해야 하니 새 기능은 매번 두 곳에 들어가고, 결국 옛 판을 못 닫아서 세 번째 판을 열게 됩니다.