API 버전: 호환되는 마이그레이션 준비

게시 04/05/2026 · 업데이트 23/10/2026 · API와 서비스 연동 · 6 분 읽기 · 작성 Cyber Intelligence Embassy

핵심 요약

번호 변경만으로 소비자를 보호할 수는 없습니다. 호환성에는 메시지와 실제 클라이언트가 의존하는 동작이 포함됩니다.

이 글의 목차

클라이언트 관점에서 검토

표는 검토 기준이며 보편적 보장이 아닙니다. 추가 필드가 엄격한 판독기를 방해하거나 새 열거값이 빠짐없는 분기를 깨뜨릴 수 있습니다. 클라이언트, 라이브러리, 가정을 파악하세요.

변경	확인할 위험	필요한 증거
필드 삭제·이름 변경	읽기 불가능	명시적 이전과 클라이언트 테스트.
선택 필드 추가	엄격한 읽기 또는 이름 충돌	기존 소비자 테스트.
응답 열거값 추가	누락된 분기 처리	알 수 없는 값의 처리 정의.
기본값 변경	다른 업무 결과	명시값 없는 사례 비교.

공존 계획

이전·신규 구조, 기본값, 오류, 페이지 이동, 권한을 설명하고 대표 소비 사례로 계약 테스트를 하세요.
버전 선택 방식을 명시하세요. 서비스 버전과 OpenAPI 문서 버전을 구분하고 캐시와 게이트웨이를 확인하세요.
일정, 이전 안내, 연락처를 공개하세요. 실제 사용을 적정하게 측정하고 데이터와 호환되는 복귀를 준비하세요.

사용 중단 예고와 종료 구분

Deprecation은 더 이상 권장되지 않는 리소스를 표시하고, Sunset은 예상 이용 종료 시점을 알릴 수 있습니다. 헤더가 클라이언트를 이전하지는 않습니다. 종료 전 남은 소비자, 의무, 복구 절차를 검토하세요.

1차 자료

소비자 영향에 따른 버전 관리

URL에 숫자를 추가하는 것만으로는 기존 클라이언트를 유지할 수 없습니다. 경로가 동일하더라도 유형, 예상 값, 동작 또는 오류 응답이 변경되면 호환되지 않을 수 있습니다.

활성 클라이언트 목록 및 사용 현황 파악
이전 클라이언트 버전을 새 계약에 대해 테스트
공존 기간을 게시하고 사용 중단 전에 사용량을 검사

1차 자료: IETF RFC 9457 — Problem Details for HTTP APIs. 관련 방법: 실무 가이드 읽기.

비동기 API 작업

요청 접수가 작업 완료를 증명하지 않습니다.

계정, 작업 및 재사용 식별자
상태, 시각, 간격 및 만료
산출물, 오류, 취소 및 남은 영향
허용된 단일 작업과 단절 후 확인한 결과

재현 가능한 수락 사례

가상 예시입니다. 고객이나 실제 관측 결과를 나타내지 않습니다.

사례 입력 보기

{
    "job_id": "J-42",
    "timeline": [
        {
            "elapsed_seconds": 0,
            "http": 202,
            "state": "pending"
        },
        {
            "elapsed_seconds": 5,
            "http": 200,
            "state": "running"
        },
        {
            "elapsed_seconds": 6,
            "http": 200,
            "state": "cancel_requested"
        },
        {
            "elapsed_seconds": 7,
            "http": 200,
            "state": "succeeded"
        }
    ]
}

예상 판단

상태 조회의 200 응답은 처리 완료를 의미하지 않습니다. 취소 요청 후에도 확인된 최종 결과를 기준으로 판단합니다.

취소 요청이 너무 늦은 경우

가상 사례: 동일한 작업 J-42를 제출 후 경과한 초로 추적합니다. 상태 이름은 이 예시의 계약에서 정의하며 HTTP가 규정하지 않습니다.

시점	응답과 상태	확인 가능한 결론
+0 s	HTTP 202 · pending	처리가 접수되었지만 최종 결과는 확인되지 않았습니다.
+5 s	HTTP 200 · running	상태 조회는 성공했지만 작업은 계속 실행 중입니다.
+6 s	HTTP 200 · cancel_requested	중지 요청이 기록되었지만 취소는 아직 확인되지 않았습니다.
+7 s	HTTP 200 · succeeded	처리가 먼저 완료되었습니다. 확인된 성공을 표시하고 영향을 점검합니다. 취소되었다고 표시하지 않습니다.

Microsoft — Asynchronous request-reply

202가 나중의 완료를 증명할까?

아니다. 처리를 위한 접수를 알릴 뿐 최종 결과는 아니다. 작업 상태를 확인한다.

1차 자료: MDN — 202 Accepted. 관련 방법: 실무 가이드 읽기.

소프트웨어 업데이트: 서명자 변경 확인

서명된 산출물이 승인한 제작자, 빌드 과정과 버전에 해당하는지 판단합니다.

새 패키지를 검사하기 전에 허용 제작자, 키 또는 인증서 신원, 발급자와 빌드 과정을 기록합니다. 소프트웨어 및 이미 신뢰한 확인 경로와 연결합니다. 검사 대상이 혼자 자신의 수용 정책을 정하게 하지 않습니다.
받은 파일의 다이제스트를 증명 대상과 대조합니다. 예정한 신뢰 루트로 서명을 검증한 뒤 신원, 빌더와 매개변수를 확인합니다. 다른 신원의 암호학적으로 유효한 서명은 서비스 정책을 충족하지 않습니다.
공지된 교체, 예상 밖 발급자, 서명 누락과 다른 파일을 시험합니다. 새 신원이 미확인되면 산출물을 보류합니다. 승인과 복귀 방식을 기록합니다. 서명이 취약점 부재를 증명하지는 않습니다.

재현 가능한 수락 사례

가상 예시입니다. 고객이나 실제 관측 결과를 나타내지 않습니다.

사례 입력 보기

{
    "signature_valid": true,
    "digest_matches": true,
    "expected_signer": "approved-publisher",
    "observed_signer": "different-publisher",
    "expected": "hold_for_independent_confirmation"
}