개발자를 잃지 않고 API를 비추천 처리하는 방법

API를 비추천 처리한다는 것은, 무언가가 오늘은 여전히 작동하지만 정해진 날짜에 작동을 멈춘다고 알리고, 그 약속의 두 절반을 모두 지키는 것을 뜻한다. 대부분의 비추천 처리는 두 번째 절반에서 실패한다. 날짜가 조용히 미뤄지거나, 그 날짜가 오는데 공지를 한 번도 보지 못한 호출자가 오류를 통해 알게 된다. 비추천 처리가 끝나는 것은 영향을 받은 모든 호출자가 이전을 마쳤거나, 아직 하지 않았다는 사실을 개별적으로 전달받았을 때다.

API 비추천 처리란 무엇인가

비추천 처리는 엔드포인트, 필드, 버전이 사라진다고 알리는 것과 실제로 제거하는 것 사이의 기간이다. 그 기간 동안 예전 동작은 계속 작동하고, 문서는 그것이 사라질 것이라고 말하며, 모든 응답은 기계가 읽을 수 있는 경고를 담는다. 제거는 별개의, 더 나중에 일어나는 사건이며, 흔히 서비스 종료라고 불린다. 이 둘은 자주 혼동되며, 바로 그 혼동이 피해를 만든다. “비추천”이 “이미 사라졌을 수도 있다”를 의미하기 시작하면, 호출자는 두 단어 모두를 더 이상 신뢰하지 않게 된다.

비추천 처리 기간은 얼마나 되어야 하는가

호출자가 그것을 알아채고 작업을 처리할 수 있을 만큼 충분히 길어야 하며, 여러분이 그것을 쓴 시점이 아니라 공지가 실제로 그들에게 도달한 시점부터 재야 한다. 90일이 공개 웹 API의 흔한 최소치다. 최종 사용자가 설치하는 소프트웨어에 내장된 것이라면 12개월이 보통이다. 그 수정이 사용자의 릴리스 과정을 통해서도 출시되어야 하기 때문이다. Google의 버저닝 가이드인 AIP-185는 합리적인 전환 기간을 요구하고 베타 기능을 제거할 때조차 180일을 권장하며, Kubernetes는 자체 비추천 처리 정책을 개월 수가 아니라 릴리스 횟수로 문서화한다. 이는 호출자가 버전별로 업그레이드할 때 올바른 단위다.

기간을 하나 정해, 그것을 정책으로 문서에 적어두고, 변경마다 다시 결정하는 것을 멈춰라. 공표된 정책은 모든 비추천 처리를 협상에서 규칙의 적용으로 바꾼다.

비추천 처리 정책을 문서로 적어두는 것은 창의 시작을 다룬다. API 버전 종료하기는 기간이 실제로 다 되어 버전이 작동을 멈출 때 마지막에 필요한 별개의 공지를 다룬다.

비추천 처리 일정

첫날에 함께 발표되는 네 개의 날짜. 각각은 그것이 도래할 때 별개의 체인지로그 항목이 되므로, 체인지로그만 읽는 사람에게는 그 이야기가 네 번 전해진다.

1. 발표한다. 항목은 무엇이 비추천되는지, 왜인지, 무엇으로 대체되는지, 그리고 서비스 종료일을 말한다. 예전 기능에 대한 문서는 이전 경로를 링크하는 배너를 얻는다. 응답은 아래 설명되는 헤더를 얻는다.
2. 중간 지점에서 상기시킨다. 두 번째 항목과 함께, 여전히 예전 동작을 사용하고 있는 모든 호출자에게 직접 메시지를 보낸다. 이것은 사용량 데이터가 필요한 단계다. 누가 아직도 비추천된 엔드포인트를 호출하고 있는지 나열할 수 없다면 이 단계를 할 수 없으며, 그것은 다음 비추천 처리 전에 고쳐둘 가치가 있다.
3. 날짜 직전에 잠시 차단한다. 짧은 시간, 한 시간이나 하루 동안 예전 동작에 오류를 반환한 다음 복원한다. 모든 공지를 놓친 호출자는 아직 시간이 남아 있는 지금 그것을 알게 된다. GitHub는 API의 비밀번호 인증을 은퇴시키기 전에 예정된 브라운아웃을 사용했으며, 이것은 이 목록에서 가장 효과적인 단일 단계다.
4. 서비스 종료. 제거한다. 그것을 대체하는 오류는 대체재를 이름으로 밝히고 이전 가이드를 링크한다. 그 오류를 오랫동안 유지하라. 404는 호출자에게 아무것도 말해주지 않는다.

비추천 처리 공지는 무엇을 말해야 하는가

비추천 처리 공지는 무엇이 사라지는지, 언제 멈추는지, 대신 무엇을 써야 하는지, 그리고 누가 영향을 받는지를 말한다. 그 형태를 채운 예시는 다음과 같다.

GET /v1/reports/daily는 비추천되었으며 2027년 3월 1일에 작동을 멈춥니다. 안정된 스키마와 페이지네이션으로 같은 데이터를 반환하는 GET /v2/reports?granularity=day로 대체됩니다. 지난 30일 동안 v1 엔드포인트를 호출한 214개의 연동에 영향을 줍니다. 여러분의 것이 그중 하나라면 이 공지를 이메일로도 받게 됩니다. 이전 가이드: [링크]. 2027년 3월 1일까지는 아무것도 바뀌지 않습니다. 그 날짜부터 v1 엔드포인트는 이 항목으로의 링크와 함께 410 Gone을 반환합니다.

모든 문장이 독자가 필요로 하는 무언가를 담고 있다. 영향받는 연동의 수는 각 독자에게 계속 읽어야 할지를 알려준다. “까지는 아무것도 바뀌지 않습니다”는 영향을 받지 않는 사람들이 탭을 닫게 해주는 문장이다. 체인지로그 예시 페이지는 이 형식을 일관되게 쓰는 팀들의 항목을 모아 놓았으며, 자신의 첫 항목을 쓰기 전에 그중 세 개를 읽어볼 가치가 있다.

비추천된 엔드포인트는 어떤 헤더를 보내야 하는가

발표일부터, 비추천된 엔드포인트로부터 오는 모든 응답에 Deprecation, Sunset, 그리고 후속으로의 Link를 보내라. Deprecation 헤더는 비추천 처리가 발효된 날짜를 담고, Sunset 헤더는 엔드포인트가 응답을 멈추는 날짜를 담으며, Link: <url>; rel="successor-version"은 대신 무엇을 써야 하는지를 가리킨다.

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/changelog/daily-reports>; rel="deprecation"

대부분의 호출자는 그 헤더를 직접 읽지 않을 것이다. 그 가치는 호출자의 HTTP 클라이언트, 게이트웨이, 모니터링이 그것을 읽을 수 있다는 데 있으며, 그것이 여러분의 비추천 처리를 여러분 쪽의 페이지가 아니라 그들 쪽의 경보로 바꾼다. 여러분이 배포하는 SDK는 그것을 볼 때 경고를 로그로 남겨야 한다.

누가 통보받았고, 그것을 어떻게 아는가

이것은 서비스 종료가 조용히 지나갈지 지원 문의로 이어질지를 결정하는 단계이며, 체인지로그만으로는 하기 가장 어려운 단계다. 체인지로그 항목은 체인지로그를 읽는 모든 사람에게 알린다. 비추천 처리는 코드가 실제로 실패할 특정 사람들에게 도달해야 하며, 그들을 찾아내는 일반적인 방법은 중간 지점 리마인더가 필요로 하는 것과 같은 사용량 데이터다. 즉, 최근 비추천된 동작을 호출한 API 키, 앱, 계정이다.

우리가 운영하는 루프는 이렇다. 항목은 비추천 처리를 추가하는 pull request로부터 초안이 작성되고, 사람이 문구와 날짜를 검토하며, 발행되고 나면 그 항목 자체가 통지가 된다. 그 문제에 대한 위젯 피드백이나 대체재 요청이 pull request가 닫는 GitHub issue가 된 사람은 누구든, 그것이 출시되었다는 코멘트를 그 issue에서 받으며, 그 항목으로의 링크가 함께 온다. 피드와 위젯은 나머지 모든 사람에게 같은 항목을 제공한다. API 체인지로그의 다른 모든 항목과 함께다. 우리가 하지 않는 것은 사람이 발행하기 전에 비추천 처리를 “출시됨”으로 만드는 것이다. 잘못된 날짜가 적힌 공지는 공지가 없는 것보다 나쁘다.

여러분의 도구가 무엇이든, 서비스 종료일에 답할 수 있어야 하는 질문은 이것이다. 지난주까지 누가 이것을 여전히 쓰고 있었으며, 그중 누구에게 직접 알렸는가. 답이 “그것에 대해 게시했다”라면, 그 서비스 종료는 아직 준비되지 않은 것이다.

비추천 처리와 버저닝의 차이는 무엇인가

버저닝은 새로운 것이 존재하는 동안 예전 동작을 계속 이용 가능하게 유지하는 방법이고, 비추천 처리는 예전 것을 은퇴시키는 방법이다. 이전 버전에 대한 비추천 처리 정책이 없는 새 API 버전은 둘 다를 영원히 운영하겠다는 약속일 뿐이다. 버저닝 없는 비추천 처리는 지연이 붙은 파괴적 변경이다. 둘 다 필요하며, 버전은 그중 더 쉬운 절반이다. GraphQL은 이름을 붙일 가치가 있는 예외다: 보통 거기에는 올릴 버전 번호 자체가 없으며, GraphQL 스키마 비추천 처리는 하나의 공유된 스키마가 대신 지시어로 필드를 은퇴시키는 법을 다룬다.

FAQ

비추천된 엔드포인트는 예전과 정확히 똑같이 계속 작동해야 하는가? 그렇다, 서비스 종료일까지는. 허용되는 유일한 변경은 추가된 헤더와, 막바지에 미리 알린 예정된 브라운아웃뿐이다.

은퇴한 엔드포인트는 어떤 상태 코드를 반환해야 하는가? 410 Gone이며, 대체재와 체인지로그 항목을 가리키는 Link 헤더와 본문을 함께 담는다. 404는 그 URL이 애초에 존재한 적 없다고 말하는 것이며, 그것은 거짓이고 도움이 되지 않는다.

비추천 처리 기간을 단축할 수 있는가? 보안상의 이유로만 가능하다. 예전 동작이 악용 가능하다면 그렇다고 말하고, 기간을 단축하고, 체인지로그에 의존하는 대신 영향을 받는 모든 호출자에게 직접 알려라.

필드도 비추천 처리해야 하는가, 아니면 엔드포인트 전체만 하면 되는가? 필드, 파라미터, enum 값, 기본값, 헤더는 모두 같은 처리를 필요로 한다. 각각이 올바른 호출자를 망가뜨릴 수 있기 때문이다. 제거된 필드는 가장 흔한 비추천 처리이면서 가장 자주 빠뜨려지는 것이기도 하다.

이 글의 기술적 내용은 독립적으로 검토되지 않았습니다. 잘못된 부분이 있으면 알려 주세요. 바로잡겠습니다.

changeloop 관련 페이지: 개발자 문서, changelog 예시