Stripe API 버전 관리, 작동 방식과 따라 할 점

Stripe API 버전 관리는 날짜로 이루어진다. 모든 계정은 릴리스 날짜를 딴 API 버전에 고정되며, 개별 요청은 Stripe-Version 헤더로 그 고정을 덮어쓸 수 있다. 이 글을 쓰는 시점(2026년 10월)에 Stripe 문서의 현재 버전은 2026-09-30.endive이며, 훨씬 작은 API도 주말 하루면 같은 방식을 따라 할 수 있다.

아래의 모든 Stripe 관련 사실은 Stripe 자체 페이지에서 가져왔으며, 사용한 자리에 링크를 달았다.

Stripe API 버전 관리는 어떻게 작동하는가

Stripe는 모든 계정에 기본 API 버전을 부여하고, 버전을 지정하지 않은 모든 요청은 그 버전을 쓴다. 호출하는 쪽은 기본값을 바꾸거나 개별 요청에 버전을 지정하는 방식으로 언제 옮길지 스스로 선택한다.

Stripe의 엔지니어링 글에 따르면 계정은 처음 API 요청을 보낼 때 고정된다. 계정은 “automatically pinned to the most recent version available”가 되고, 그 이후의 모든 호출에는 그 버전이 암묵적으로 할당된다.

버전 문자열은 날짜다. 2024-09-30.acacia 릴리스부터는 2026-09-30.endive처럼 이름도 함께 붙는다. 날짜는 버전의 순서를 정하고, 이름은 그 버전이 어느 메이저 릴리스 계열에 속하는지 알려준다.

요청마다 버전은 어떻게 선택하는가

요청에 Stripe-Version 헤더를 보내거나 SDK에서 버전을 설정한다. Stripe의 업그레이드 가이드가 헤더 형태를 보여주며, 같은 호출이 라이브 환경과 테스트 환경 모두에서 작동한다.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Stripe의 가이드에 따르면 SDK에서 버전을 전역으로 또는 요청마다 설정하면 응답 객체도 그 버전으로 돌아온다.

Stripe는 계정 기본값에 기대지 말라고도 권한다. 요청마다 헤더나 고정된 SDK로 버전을 지정해서, 대시보드 설정이 아니라 여러분의 코드가 버전을 결정하게 하라는 것이다.

SDK는 언어에 따라 고정 방식이 다르다. 문서에 따르면 동적 타입 라이브러리의 최신 버전은 해당 SDK 릴리스가 나왔을 때의 최신 API 버전을 쓰고, 강한 타입을 쓰는 라이브러리(Java, Go, .NET)는 그 버전에 고정된다. 라이브러리 버전을 설치하는 것이 사실상 API 버전을 선택하는 일이다.

버전이 바뀌면 웹훅은 어떻게 되는가

웹훅 이벤트는 서버 코드가 쓰는 버전이 아니라 그 엔드포인트에 연결된 API 버전으로 렌더링된다. Stripe 문서에 따르면 이벤트는 엔드포인트를 만들 때 설정한 버전을 쓰고, 설정하지 않았다면 계정 기본값을 쓴다. SDK 버전을 바꿔도 웹훅 핸들러가 받는 내용은 바뀌지 않는다.

그래서 요청 경로와 이벤트 경로가 서로 다른 두 버전에 놓일 수 있다. 이벤트 대상의 경우 snapshot_api_version은 대상을 만들 때만 설정하므로, 다른 버전을 쓰려면 새 대상을 만들어야 한다.

이에 대한 Stripe의 업그레이드 경로는 병렬 실행이다. 목표 버전으로 새 엔드포인트를 만들고, 같은 이벤트를 양쪽에 보내고, 핸들러가 한쪽은 처리하고 다른 쪽은 무시하도록 가르친 다음, 전환하고 기존 엔드포인트를 비활성화한다. 겹치는 동안 모든 이벤트가 두 번 도착하므로 핸들러는 멱등해야 한다. 이벤트를 내보내는 어떤 API에도 따라 할 만한 좋은 패턴이며, 이런 방식이 필요해지는 페이로드 변경은 웹훅 체인지로그에서 공지한다.

월간 릴리스와 메이저 릴리스는 무엇인가

2024-09-30.acacia 릴리스부터 Stripe는 파괴적 변경 없이 매달 새 API 버전을 내놓고, 연 두 번 파괴적 변경이 담긴 버전으로 시작하는 새 메이저 릴리스를 낸다. 버전 관리 페이지에 따르면 코드를 업데이트하지 않고도 어떤 월간 릴리스로든 업그레이드할 수 있지만, 메이저 릴리스는 변경이 필요할 수 있다.

메이저 릴리스에는 이름이 붙는다. 버전 관리 페이지는 Basil을 예로 들고, 이 절차에 대한 Stripe의 발표는 이름이 식물에서 왔고 Acacia로 시작하며, 월간 릴리스는 바로 앞 메이저 릴리스의 이름을 유지해서 그 이름이 안전하게 올려도 된다는 신호가 된다고 밝힌다. Stripe의 changelog에 사용 중인 이름들이 나열되어 있고, 이 글을 쓰는 시점에 가장 최신 항목은 2026-09-30.endive이다.

그래서 날짜는 “얼마나 새로운가”에 답하고, 이름은 “파괴적 경계인가”에 답한다. Stripe의 발표는 예외의 여지도 남겨 둔다. 그렇게 하지 않으면 통합이 심각한 영향을 받을 상황에서는 주기를 벗어난 파괴적 변경을 낼 권리를 보유한다. 이 발표는 Stripe’s new API release process에 있다.

Stripe API의 최신 버전은 무엇인가

이 글을 쓰는 시점(2026년 10월)에 Stripe의 버전 관리 페이지는 현재 버전이 2026-09-30.endive라고 밝히고, changelog도 같은 버전을 가장 최신으로 나열한다. Stripe는 매달 새 버전을 내므로 글에 인쇄된 문자열은 금세 낡는다. 무언가를 고정하기 전에 실시간 changelog를 읽고, 테스트한 버전으로 고정하라.

Stripe는 오래된 버전을 어떻게 계속 작동하게 하는가

Stripe는 모든 파괴적 변경을 독립적인 버전 변경 모듈로 작성하고, 데이터의 가장 최신 형태에서부터 거꾸로 그 모듈들을 적용하는 방식으로 오래된 버전을 살려 둔다. 그 메커니즘은 API 버전 관리에 대한 엔지니어링 글에 설명되어 있다.

각 모듈은 무엇을 바꾸는지 선언하고, 변경을 문서화하고, 변환 함수를 포함한다. 이 글은 필드가 문자열에서 해시로 바뀌는 예를 든다. 응답을 만들 때 시스템은 목표 버전을 알아낸 뒤, 시간을 거슬러 올라가며 그 버전에 이를 때까지 도중에 만나는 모듈을 하나씩 적용한다.

이 설계에서 두 가지 부수 효과가 따라오며, 글은 둘 다 짚는다. 모듈이 자신이 건드리는 필드와 리소스를 선언하므로 Stripe는 배포할 때 이 모듈들로 API changelog를 생성할 수 있다. 그리고 계정의 버전을 알고 있으므로 문서가 그 버전에 맞춰지고, 그 버전 이후의 하위 호환되지 않는 변경에 대해 경고할 수 있다.

비용은 얼마이며 작은 API는 무엇을 따라 해야 하는가

버전 관리에는 엔지니어링의 주의력이 들고, Stripe도 그렇게 말한다. 엔지니어링 글은 유지 보수 부담을 인정하며, 새 코드를 작성하면서 옛 동작에 대해 생각할 일이 적을수록 좋다는 목표를 밝힌다. 또한 버전 변경이 아예 필요하지 않도록 릴리스 전에 가벼운 API 검토를 거친다고 설명한다.

작은 API는 오래된 버전마다 모듈 사슬을 감당할 수 없고, 그럴 필요도 없다. 가치를 담은 부분만 따라 하라.

1. 날짜 기반 버전. 날짜는 무엇이 “메이저”인지 판단할 필요가 없고, 호출하는 쪽이 읽을 수 있다. API 버전 관리 모범 사례 글은 이것을 URL 방식, 헤더 방식과 비교한다.
2. 고정된 기본값. 처음 사용할 때 계정이나 키를 그 버전에 고정해서, 작동 중인 통합 아래에서 API가 바뀌는 일이 없게 한다.
3. 요청별 덮어쓰기. 호출하는 쪽이 확정하기 전에 프로덕션에서 호출 한 건으로 새 버전을 시험해 볼 수 있게 하는 헤더.
4. 웹훅 엔드포인트의 버전. 이벤트 페이로드가 호출하는 쪽이 가장 자주 놀라는 곳이다.
5. 버전마다 체인지로그 항목 하나. 버전, 날짜, 영향받는 대상, 해야 할 일을 밝힌다. 무엇이 파괴적 변경인가는 새 버전에 무엇이 속하는지 가리는 기준이고, API 체인지로그 글은 항목 자체를 다룬다.

지원하는 버전의 수 때문에 어쩔 수 없게 될 때까지는 모듈 사슬을 건너뛰어라. 운영 중인 버전이 두세 개라면 몇 개의 분기와 종료일로 감당할 수 있으며, API 버전 종료가 그 과정을 안내한다.

날짜가 있는 체인지로그를 발행한다면, 버전 이력은 그 항목들만큼만 좋다. Changeloop에서는 병합된 pull request마다 항목 초안이 만들어지고, 체인지로그 페이지와 피드에 발행되기 전에 사람이 승인하도록 보류된다. 버전별 항목이 작성되는 자리가 바로 거기이며, 사람이 거치는 한 번의 관문이 호출하는 쪽이 무엇을 해야 하는지를 말해 주는 검토다.

FAQ

Stripe API의 최신 버전은 무엇인가? 이 글을 쓰는 시점(2026년 10월)에 Stripe의 버전 관리 페이지는 현재 버전이 2026-09-30.endive라고 밝힌다. Stripe는 매달 새 버전을 내므로 고정하기 전에 changelog를 확인하고, 계정 기본값에 기대는 대신 버전을 코드에 적어 두라.

요청에 Stripe API 버전은 어떻게 설정하는가? Stripe-Version: 2026-09-30.endive처럼 Stripe-Version 헤더를 보내거나, 서버 쪽 SDK에서 버전을 전역으로 또는 요청마다 설정한다. 둘 다 없으면 요청은 계정의 기본 버전을 쓰며, 이는 Workbench에서 직접 설정한다.

웹훅은 내 요청과 같은 Stripe API 버전을 쓰는가? 꼭 그렇지는 않다. 웹훅 이벤트는 엔드포인트를 만들 때 설정한 버전을 쓰고, 설정하지 않았다면 계정 기본값을 쓴다. SDK를 업그레이드해도 웹훅 핸들러가 받는 페이로드는 바뀌지 않으므로, 엔드포인트는 따로 업그레이드하고 병렬로 테스트하라.

Stripe식 날짜 버전 관리는 작은 API에 맞는가? 날짜 버전, 고정된 기본값, 요청별 헤더, 버전마다 체인지로그 항목 하나는 비용이 적게 들고 따라 할 가치가 있다. 오래된 버전을 한꺼번에 많이 지원하게 되기 전까지는 내부의 버전 변경 모듈 사슬은 그렇지 않다. 운영 중인 버전 두 개와 오래된 쪽의 종료일부터 시작하라.

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

changeloop 관련 페이지: 개발자 문서