버전과 호환성

API의 메이저 버전은 /v1 하나뿐이며, 이 버전은 늘어나기만 해요. 오늘 작성한 연동은 새 기능이 추가되어도 계속 동작해요. 연동이 의존하는 것은 이름이 바뀌거나, 제거되거나, 새로운 의미를 갖지 않아요.

버전 번호

API에는 1.62.0 같은 버전 번호가 있어요. 버전 번호는 릴리스마다 바뀌어요.

• 엔드포인트, 필드, 이벤트처럼 무언가가 추가되면 마이너 번호가 바뀌어요.
• 설명이나 메시지 텍스트만 고치고 다른 것은 바뀌지 않으면 패치 번호가 바뀌어요.

주소가 제공하는 버전은 언제든 확인할 수 있어요.

GET /v1/health에도 version 값이 있지만, 이것은 API의 버전이 아니라 그 주소를 제공하는 Sursa 릴리스의 버전이에요.

마이너 버전은 고를 수 없어요. 모든 요청은 현재 버전이 처리해요. 아래 규칙 덕분에 그래도 안전해요.

/v1에서 바뀔 수 있는 것

다음 변경은 어느 마이너 버전에서든 나올 수 있어요. 이런 변경으로 깨지지 않도록 연동을 작성하세요.

• 새 엔드포인트.
• 새 선택 파라미터와 요청 필드. 이것을 보내지 않는 요청은 전과 같이 동작해요.
• 응답, 객체, 이벤트의 새 필드.
• 새 카드 상태나 새 이벤트 유형처럼 응답에 있는 열거형의 새 값.
• 새 오류 코드와 새 응답 헤더.
• 최대 길이가 늘거나 범위가 넓어지는 것처럼 덜 엄격해지는 한도.
• 오류의 message 텍스트와 설명의 문구 수정.

코드가 견뎌야 하는 것

• 모르는 필드는 무시하세요. 응답에 예상보다 많은 필드가 있어도 실패하지 말고, 그런 필드를 거부하는 엄격한 스키마를 쓰지 마세요.
• 모르는 열거형 값을 받아들이세요. 응답의 모든 열거형은 값이 늘어날 수 있어요. 모르는 값은 오류가 아니라 “기타”로 처리하세요.
• 모르는 이벤트 유형은 건너뛰세요. 웹훅에서도 스트림에서도 마찬가지예요.
• 모르는 오류 코드는 HTTP 상태로 처리하세요. 오류를 참고하세요.
• JSON 객체의 필드 순서에 의존하지 마세요. 메시지의 정확한 텍스트에도 의존하지 마세요.

/v1에서 절대 바뀌지 않는 것

• 경로, 파라미터, 필드, 열거형 값은 이름이 바뀌거나 제거되지 않아요.
• 필드의 타입은 바뀌지 않으며, 단위가 바뀌는 것처럼 필드가 새로운 의미를 갖는 일도 없어요.
• 오늘 받아들여지는 요청이 나중에 거부되지 않아요.
• 성공 응답의 상태 코드는 그대로 유지돼요.
• 오류 코드는 의미가 유지되며, 오류 응답의 detail 필드도 형식이 유지돼요.
• 이벤트 유형은 이름이 바뀌거나 제거되지 않으며, 이벤트의 data에는 필드가 추가되기만 해요.

호환성이 깨지는 변경

호환되지 않는 변경이 필요해지면 /v1 옆에 /v2 같은 새 메이저 버전으로 출시해요. /v1은 바뀌지 않고 계속 동작하며, 두 버전이 나란히 운영돼요.

경로의 지원을 종료할 때는 다음과 같이 진행해요.

1. 명세에서 deprecated로 표시하고, 변경 내역에 사용이 중단되는 날짜와 함께 올려요.
2. 그 경로의 응답에 Deprecation: true와 Sunset: <date> 헤더가 붙어요.
3. 공지 후 최소 180일 동안 계속 동작해요. 그 경로를 쓰는 API 키가 있는 조직에는 최소 90일 전에 서면으로 알려요.
4. 지원 종료일 이후 90일 동안은 410 상태와 api.gone 코드로 응답해요.

로그나 모니터링에서 Deprecation 헤더를 지켜보세요. 사용하는 경로가 곧 없어진다는 가장 빠른 신호예요.

변경 사항 확인하기

이 포털의 변경 내역에는 모든 릴리스와 그때 추가되거나 사용 중단 예정이 된 항목이 나와 있어요. 연동을 업그레이드하기 전에, 연동을 만들 때 기준으로 삼은 버전 이후의 항목과 코드를 비교하세요.