기술 및 인프라 → API Versioning

API 버전 설정

1) 왜 필요한가

• 석방 중 사고의 위험을 줄입니다
• 개선과 안전을 예약할 수 있습니다
• 파트너 마이그레이션을위한 비즈니스 예측 가능한 타임 라

2) 변경 분류

PATCH (깨지지 않음): 계약을 변경하지 않고 수정 (선택적 필드 추가, 검증 수정).
MINOR: 백 호환 확장 (새 엔드 포인트, 기본값이있는 필드).
메이저 (파괴): 구조 변경, 의미론 또는 필드/엔드 포인트 삭제.

SemVer 'MAJOR가 권장됩니다. 미노르. 아티팩트 용 PATCH (SDK/스키마) 는 "외부" API 번호를 단순화 할 수 있습니다 (v1, v2).

3) REST 버전 지정 모델

1. 허리까지:

'GET/v1/payment/{ id}'

장점: 투명하고, 도달 가능하며, 경로가 쉽습니다. 단점: 문서의 중복, 미묘하게 진화하기가 더 어렵습니다.

2. 헤더 (컨텐츠 협상) 에서:

'수락: 응용 프로그램/vnd. 회사. 지불. v2 + json '

장점: 유연성, 탭에 "쓰레기" 가 없으며 미디어 유형의 편리한 진화. 단점: 브라우저에서 디버깅하기가 더 어렵습니다. 훈련 된 클라이언트가 필요합니다.

3. 사용자 정의 헤더에서:

'X-API-Version: 2' (и독일어 'Api-Version: 2025-09-01')

장점: 수문에. 단점: 표준이없고 캐시에주의하십시오.

4. 날짜 기반 버전:

핀 테크/보고에 좋습니다: 예측 가능한 변화의 "컷" (예: 분기 별).

5. 리소스/모델 버전:

권장 사항: 외부 통합에 대해- '² vN' + 거부/일몰 헤더; 내부의 경우-게이트웨이 및 플랫폼이 지원하는 경우 '수락' 또는 버전 헤더를 수락 할 수 있습니다.

4) 그래프 QL

우선 순위-글로벌 버전이 없습니다. 필드/유형 및 박탈의 추가를 통한 진화 ('@ 더 이상 사용되지 않음 (이유:... "")').
파괴 변경 - 마이그레이션 안내서가있는 "큰" 창 (다양한 스키마 네임 스페이스) 에서만 가능합니다.
"n + 1" 을보고 기존 필드의 의미를 변경하지 마십시오.

5) gRPC/프로토 타입

필드 번호는 불변입니다. 삭제 된 필드를 '예약' 으로 표시하십시오.
안전한 기본값으로 필드를 추가합니다.
자동 호환성 검사를 위해 파괴/보풀을 사용하십시오.
버전 패키지/모듈: '패키지 결제. v1; '→' 지불. v2 '.

6) 이벤트 API (EDA)

이벤트 체계는 동일한 계약입니다. 스키마 레지스트리 (Avro/JSON-Schema/Proto) 에 저장하십시오.
주제와 버전: '지불. v1. ',' 지불 승인. v2. 승인 된 '.
깨는 변화-새로운 유형의 이벤트 또는 새로운 주제.
진화 보장: LTS 기간 동안 소비자에게 역 호환됩니다.

7) 박탈 정책 및 EOL

• 비난: 변경 로그 및 사양의 레이블 (OpenAPI/GraphQL SDL), 헤더
• '우울증: 가능한 경우' 일몰: 화, 2026 년 3 월 31 일 00:00:00 GMT '.
• 커뮤니케이션: 이메일/파트너 포털, 웹 후크 알림, 릴리스 메모.
• 용어: MINOR - 3-6 개월의 지원, MAJOR - 9-18 개월 (중요도에 따라 다름).
• 시간 창: "API Versioning Policy" 에서 수정합니다.

8) 라우팅 및 릴리스

게이트웨이 API (Kong/Apigee/Nginx/Envoy): 접두사 '/v1/', 헤더 또는 미디어 타입 규칙.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: 트래픽의 1-5% 로 새 버전을 굴리고 계약 오류 메트릭 및 로그를 비교하십시오.
기능 플래그: 계약을 변경하지 않고 동작을 숨깁니다.
다운 타임 마이그레이션: MAJOR을 사용하면 데이터 스키마의 이중 쓰기/읽기를 제공합니다.

9) 계약 테스트 및 호환성 제어

OpenAPI Diff (또는 swagger-diff) -MINOR/PATCH가 스키마를 깨뜨리지 않는지 확인하십시오.
스펙트럼 린팅-스타일, 필요한 메타 데이터 (버전, 우울증).
소비자 주도 계약 (Pact) -공급자가 고객을 깰 수 없도록합니다.
차이를 끊는 것입니다.
CI는 MAJOR을 높이지 않고 변화를 깨뜨릴 수 있습니다.

10) 문서 및 SDK

사양 버전: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
SemVer 및 변경 로그를 사용하여 버전 (npm/maven/pypi) 별로 SDK를 생성합니다.
주석/사용하지 않는 주석으로 SDK에서 더 이상 사용되지 않는 메소드를 표시하십시오.

11) 버전 별 관찰

• 버전 당 RPS/대기 시간/오류 ('api _ version' 레이블).
• 엔드 포인트 사용량 맵: v1에 누가 있습니까?
• 경고: "계약 불일치로 인한> 10% 4xx", "오래된 고객> T 데이트 후 X%".

12) 캐싱 및 버전

헤더/미디어 버전-Vary를 신중하게 사용하십시오

대중 교통 버전은 CDN의 캐러블성을 향상시킵니다.
'Vary: 수락, X-API 버전'.
캐시 키를 끊기 위해 MINOR 응답의 의미를 변경하지 마십시오.

13) 안전

버전을 JWT로 암호화하거나 바느질하지 마십시오. 버전은 토큰이 아닌 요청에 의해 결정됩니다.
내부 어셈블리 번호를 표시하지 않습니다. 외부 메시지에 "v1/v2" 를 사용하십시오.
MAJOR에서는 검토 검증, 한계, PII 마스킹.

14) 이주 및 자동 도우미

"Migration Guide v1 → v2" 게시: 필드 매핑 테이블, 샘플 요청/응답, 엣지 케이스.
구식 분야를 강조하는 클라이언트 (CLI) 를위한 라인터를 제공합니다.
대규모 파트너-두 가지 버전과 테스트 데이터 세트가있는 샌드 박스.

15) 반 패턴

"Eternal v1": 마감일 및 사용 지표 부족.
MINOR/PATCH의 숨겨진 변경 사항.
"쿼리 문자열의 버전" ('? v = 2 ') -캐시 및 가독성을 차단합니다.
"하나의 종점은 100 개의 플래그 값입니다": 테스트/문서화하기 어렵습니다.

16) 구현 점검표

1. 외부 및 내부 클라이언트에 대해 선택된 모델 (용지/수락/헤더).
2. 사양 및 SDK 용 SemVer, CI의 자동 브레이크 체크.
3. 우울증/일몰 정책 및 통신 템플릿.
4. 게이트웨이 라우팅 + 카나리아, 대시 보드 버전.
5. 중요한 통합 (지불, KYC, 보고) 에 대한 CDC/계약 테스트.
6. 문서/SDK/마이그레이션 가이드는 릴리스와 동시에 게시됩니다.
7. 날짜와 책임이있는 EOL 계획.

17) 예

17. 1 REST (리스트 + 헤더)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 콘텐츠 협상 2 개

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 그래프 QL (필드 박탈)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (원형)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 이벤트 모델

• '지갑. v1. 균형. 업데이트 됨 '
• '지갑. v2. 균형. '(확장 스키마가있는 새 이벤트)

제도는 레지스트리에 저장되며 제작자는 호환성을 위반하는 제도로 이벤트를 게시하지 않습니다.

18) 컨텍스트 iGaming/fintech (실습)

지불: '상태 '/' ducking _ reason' 이 확장 된 새 PSP에 대한 입력 v2; 게이트웨이에서보고를 위해 v1 → v2를 매핑합니다.
KYC: MINOR는 'pep _ screening' 필드를 추가하고 클라이언트는 v1, v2를 무시합니다.
책임있는 게임/제한: MAJOR는 한계 모델 (매일/매주) 을 변경합니다. EOL v1 이전에보고로 이중 내보내기.
규제 기관에보고: 고정 버전 날짜: '보고-2025-01'.

19) 미니 정책 (위키 예)

모델: 외부 API의 경우- '²/vN/'; 내부- '수락:... vN + json '또는' X-API-Version: N '.
SemVer: 사양 및 SDK는 'N으로 게시됩니다. 미성년자. 패치 '. MAJOR에는 RFC/ADR이 필요합니다.
호환성: MINOR/PATCH-변경 사항이 없습니다. 브레이킹 → MAJOR을 통해서만.
우울증/EOL: 90 일 이상 발표; 헤드 라인의 일몰 날짜; 중요한 고객을위한 LTS 지점.
제어: 주요 통합을 위해 CI, CDC에서 OpenAPI diff/craking.
관찰 가능성: 레이블 'api _ version' 이있는 메트릭/로그.
릴리스: 카나리아 5% 이하 24 시간, 녹색 메트릭으로 단계적으로 100%.

결과

Versioning은 "/v2 in IM "이 아니라 프로세스에 관한 것입니다: 명시 적 진화 규칙, 자동 호환성 점검, 관리 릴리스 및 통합 존중. 명확한 정책을 입력하고 모니터링 및 관찰 가능성을 자동화하면 더 이상 제품에 위협이되지 않습니다.