API 버전 관리
공개 API는 Shopify와 동일한 방식인 날짜 기반 버전을 사용하므로, 개발 대상 버전이 사용자 모르게 바뀌지 않습니다. 날짜 기반 버전은 호환되지 않는 변경의 큰 경계이며, 같은 버전 안에서도 스키마는 추가 방식으로 계속 발전합니다.
버전 이름
버전 이름은 YYYY-MM 형식이며 월은 분기 시작월입니다: 2026-01, 2026-04, 2026-07, 2026-10. 새 날짜 기반 버전은 호환되지 않는 변경이 있을 때만 만들어집니다. 그런 변경이 없는 분기는 건너뛰므로 버전은 비교적 드물게 나옵니다.
가장 앞선 개발 상태를 따라가는 unstable 버전도 있어, 안정 릴리스 전에 변경을 미리 볼 수 있습니다. 여기에 프로덕션 연동을 구축하지 마세요.
버전 선택
우선순위 순으로 두 가지 방법이 있습니다.
- URL 경로(권장): 엔드포인트에 버전을 넣습니다 —
…/backend/<subdomain>/api/2026-07/graphql. 명시적이고 캐시에 유리하며 그대로 복사해 쓸 수 있습니다. - 요청 헤더: 버전이 없는
…/backend/<subdomain>/graphql엔드포인트에X-Api-Version: 2026-07을 보냅니다.
버전을 생략하거나 알 수 없는 버전 또는 지원이 종료된 버전을 지정하면, 요청은 최신 버전이 아니라 아직 지원되는 가장 오래된 버전이 처리합니다. 호환되지 않는 변경으로 조용히 옮겨지는 일은 결코 없습니다. 계속 유지할 연동이라면 버전을 명시적으로 고정하세요.
모든 응답은 자신을 처리한 버전을 X-Api-Version 헤더로 알려 줍니다. 어떤 계약이 응답했는지 항상 알 수 있고, 기본 동작에 의존하고 있었다면 그 차이도 감지할 수 있습니다.
지원 기간
각 안정 버전은 최소 12개월 지원되며, 다음 버전과 최소 9개월 겹칩니다. 실제로는 언제나 두세 개의 버전이 살아 있어 마이그레이션에 여유 있는 기간이 확보됩니다. 버전의 지원 종료일은 해당 버전이 출시되는 날 공개됩니다.
무엇이 호환되지 않는 변경인가
같은 버전 안에서 추가 방식의 변경은 이뤄질 수 있으며, 클라이언트는 이를 허용해야 합니다.
- 새 타입, 쿼리, 뮤테이션 추가
- 기존 필드에 선택적 인자 추가
- 객체 타입에 필드 추가
- 열거형에 값 추가(따라서 열거형이 닫혀 있다고 절대 가정하지 마세요)
새 날짜 기반 버전은 진짜로 호환되지 않는 변경에만 쓰입니다. 필드나 타입의 삭제·이름 변경, null 허용 조건의 강화, 인자나 기본값의 의미 변경 등입니다. 이런 변경은 기존 버전 안에서는 결코 일어나지 않으며, 고정한 버전은 지원 종료일까지 동작을 유지합니다.
지원 중단
지원 중단은 두 가지 방식으로 알려지므로, 무언가 망가지기 전에 알 수 있습니다.
- 스키마에서. 폐기 예정 필드에는
@deprecated가 표시되고, 대체 대상을 알려 주는 사유가 함께 붙습니다. 인트로스펙션과 GraphQL Playground가 이를 모든 클라이언트에 자동으로 노출합니다. - 응답에서. 요청이 실제로 지원 중단된 필드를 해석하면, 응답에
X-Api-Deprecated-Reason헤더(와 대응하는extensions.deprecations항목)가 실려 해당 요청이 건드린 구체적인 지원 중단 항목을 알려 줍니다. 따로 찾아보지 않아도, 마주친 순간 로그에 나타납니다.
지원 중단된 필드는 공개된 최소 기간 동안 유지된 뒤 이후의 날짜 기반 버전에서 제거됩니다.