클라이언트를 잃지 않고 API 계약을 발전시키십시오.

이 가이드가 달성하는 목표

• 계약서 작성
• 오류 수정
• 호환성 테스트
• 서비스 종료 계획 수립

빠른 확인

• 각 작업은 어떤 클라이언트가 사용하는가?
• 오류 유형과 상태가 안정적인가?
• 기존 클라이언트가 변경 사항을 수용할 수 있는가?
• 재시도 시 작업이 중복될 수 있는가?
• 서비스 종료는 어떻게 발표하고 검증할 것인가?

단계별 방법

1. 1

   사용자 목록 작성

   작업, 클라이언트, 사용량, 버전 및 소유자 목록을 작성합니다. 필드를 변경하기 전에 관찰된 사용량과 가정을 구분합니다.

   결과물: 계약 종속성 맵

2. 2

   요청 및 응답 설명

   스키마, 실제 예제, 성공 및 실패 응답을 포함하는 OpenAPI 설명을 유지 관리합니다. 실행 중인 서비스와 비교하여 검증합니다.

   결과물: 버전 관리된 계약 및 적합성 테스트.

3. 3

   오류 안정화

   HTTP 상태를 의미론에 따라 사용하고, 필요한 경우 RFC 9457에 따라 문서화된 문제 유형을 사용합니다. 비밀 정보를 자세히 노출하지 않습니다.

   결과물: 테스트된 오류 카탈로그.

4. 4

   변경 사항 분류

   필수 필드, 유형, 값, 동작, 시간 초과 및 페이지네이션을 검사합니다. 대표적인 사례를 사용하여 이전 클라이언트를 새 버전과 비교하여 테스트합니다.

   결과물: 호환성 매트릭스 및 버전 결정.

5. 5

   알림의 안정성 확보

   웹훅의 경우 인증, 비정렬 전송, 중복 및 재시도 계획을 수립합니다. 반복이 가능한 경우 처리의 멱등성을 확보합니다.

   결과물: 재실행 및 승인 시나리오.

6. 6

   종료 경로를 포함한 릴리스

   마이그레이션 노트, 공존 기간 및 연락처를 게시합니다. 이전 버전 사용량을 측정하고 영향을 받는 사용자를 확인한 후에만 이전 버전을 폐기합니다.

   결과물: 마이그레이션 계획 및 폐기 증빙 자료 종료 경로를 포함한 릴리스 이전 버전 배포 마이그레이션 노트, 공존 기간 및 연락처를 게시합니다. 이전 버전 사용량을 측정하고 영향을 받는 사용자를 확인한 후에만 이전 버전을 폐기합니다. 최종 결과물: 마이그레이션 계획 및 이전 버전

관리 지표

일반적인 실수

• 버전 번호만으로 호환성이 유지된다고 가정
• 200개의 응답만 문서화
• 오류 발생 시 내부 추적 또는 비밀 키 반환
• 웹훅이 한 번만 순서대로 도착한다고 가정