[SWE-005][기초] API 약속을 지키며 기능을 바꾸는 법 > IT 기술 공유

• 목록

[이번 수업]

API 계약을 코드로 검사하며 기존 사용 프로그램을 유지하는 변경과 깨뜨리는 변경을 구분합니다.

[선수지식]

BACK-001~003의 HTTP 요청·응답, 상태 코드, REST API와 SWE-003의 자동 테스트 개념을 알면 좋습니다.

[학습목표]

1. API 계약에 포함할 항목을 설명한다.
2. 기존 소비자를 유지하는 변경과 깨뜨리는 변경을 구분한다.
3. 계약 테스트와 폐기 예고를 변경 절차에 넣는다.

[핵심개념]

API 계약은 서비스를 제공하는 쪽과 사용하는 쪽이 합의한 통신 규칙입니다. URL 경로와 HTTP 메서드, 입력 매개변수, 인증 방식, 성공·오류 상태 코드, 요청·응답 본문의 필드와 자료형을 포함합니다. 문서와 실제 동작이 다르면 소비자, 즉 API를 호출하는 프로그램은 예고 없이 실패할 수 있습니다.

OpenAPI는 언어와 무관하게 HTTP API를 기술하는 표준입니다. `paths`에는 경로와 동작을, `responses`에는 상태 코드별 응답을, 스키마에는 필드·자료형·필수 여부를 적습니다. 계약 파일은 검증과 테스트의 기준으로 버전 관리합니다.

하위 호환성은 새 서버에서도 기존 소비자가 계속 동작한다는 뜻입니다. 선택 필드 추가는 소비자가 모르는 필드를 무시할 때 대체로 호환됩니다. 필수 필드 삭제·이름·자료형 변경, 새 필수 입력, 상태 코드나 의미 변경은 깨지는 변경입니다. 열거형 값 추가도 소비자 구현에 따라 깨질 수 있어 테스트해야 합니다.

공개 API를 선언하고 변경 성격을 버전으로 알립니다. Semantic Versioning은 호환 기능 추가를 MINOR, 비호환 변경을 MAJOR 증가로 표현합니다. 오래된 기능은 즉시 제거하지 말고 대체 방법과 전환 기간을 알립니다. RFC 9745의 `Deprecation` 헤더는 폐기 시점을 알리며, 알림 자체는 자원 동작을 바꾸지 않습니다.

[따라하기]

아래 내용을 api_compat.py로 저장합니다. 실제 OpenAPI 검증기의 축소 예제로, 기존 소비자가 요구하는 필드와 자료형만 검사합니다.

```python
contract = {"id": int, "name": str}

def is_compatible(response):
    return all(
        key in response and isinstance(response[key], kind)
        for key, kind in contract.items()
    )

cases = {
    "current": {"id": 1, "name": "book"},
    "optional added": {"id": 1, "name": "book", "color": "blue"},
    "required renamed": {"id": 1, "title": "book"},
}

for label, response in cases.items():
    result = "OK" if is_compatible(response) else "BREAK"
    print(f"{label}: {result}")
```

macOS·Linux는 `python3 api_compat.py`, Windows는 `py api_compat.py`로 실행합니다. 예상 결과입니다.

```text
current: OK
optional added: OK
required renamed: BREAK
```

필수인 name을 유지한 선택 필드 추가는 통과하지만 name을 title로 바꾸면 기존 계약 검사가 실패합니다. 배포 파이프라인에서는 실제 OpenAPI 문서의 변경 비교와 대표 소비자 계약 테스트를 함께 실행하세요.

[흔한 실수]

- 서버 코드만 고치고 계약 문서와 예제, 생성 클라이언트를 갱신하지 않습니다.
- 필드 추가가 언제나 안전하다고 생각합니다. 필수 여부와 소비자의 미지 필드·열거형 처리도 확인해야 합니다.
- 같은 버전의 응답 의미를 조용히 바꾸거나 폐기 직전에만 알립니다.
- 성공 응답만 계약으로 만들고 인증 실패·입력 오류·한도 초과 응답을 빠뜨립니다.

[보안 주의]

공개 계약 예제에 실제 토큰, 내부 호스트 이름, 개인정보를 넣지 마세요. 비공개 경로나 관리 기능이 노출되지 않도록 문서의 배포 범위와 접근 권한을 분리합니다. 약한 인증은 안전한 새 방식을 병행 제공한 뒤 충분한 전환 기간을 두고 폐기하세요. 계약 테스트는 본인 소유의 개발·격리 환경에서만 실행합니다.

[직접 해볼 과제]

1. cases에 선택 필드 `stock`을 추가한 응답과 id를 문자열로 바꾼 응답을 넣고 결과를 설명하세요.
2. 자신이 만든 API 하나의 경로·메서드·입력·성공 응답·오류 응답 표를 만들고, 다음 변경을 호환 또는 깨짐으로 분류하세요.

[확인문제]

1. API 계약에는 어떤 통신 규칙이 포함되나요?
2. 필수 응답 필드의 이름을 바꾸면 왜 기존 소비자가 깨질 수 있나요?
3. 폐기 예고 기간에 기존 자원의 동작을 유지해야 하는 이유는 무엇인가요?

[다음 학습]

SWE-006에서는 계층형·클린·헥사고날 아키텍처가 의존성을 어떤 방향으로 정리하는지 배웁니다.

[공식 참고 자료]

- OpenAPI Specification 3.2.0: https://spec.openapis.org/oas/v3.2.0.html
- Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html
- RFC 9745 Deprecation 헤더: https://www.rfc-editor.org/rfc/rfc9745.html
- RFC 8594 Sunset 헤더: https://www.rfc-editor.org/rfc/rfc8594.html