---
type: template
domain: product
role: Tech Lead·아키텍처
status: active
last-reviewed: 2026-07-27
---

# API·데이터 계약

> 생산자와 소비자가 같은 요청·응답·오류·권한·데이터 의미를 독립적으로 구현하고 테스트할 수 있게 한다. 이 문서가 납품 문서 **API정의서(인터페이스 정의서)**와 **ERD·테이블정의서·코드정의서**의 **설계 단계 정본**이다 — 이 둘 없이 코드만 넘기면 "블랙박스 인계"이고, 발주사 기존 시스템 연동팀과의 협업이 붕괴한다 ([[외주 개발 산출물]]).
>
> **정본 계층**: 설계 단계 정본은 이 문서. 개발 완료 후 **납품본은 코드·schema에서 역생성**한다 ([[01_API 계약]], [[01_ERD·스키마 명세]]). 역생성본이 이 문서와 다르면 임의 반영이 아니라 **CR 또는 이 문서 갱신**으로 처리한다.

## 계약 목록

| Contract ID | 생산자 | 소비자 | 방식 | 버전 | 연결 요구 | Owner | 상태 |
|---|---|---|---|---|---|---|---|
| `API-001` | `Backend` | `Frontend / 발주사 기존 시스템` | `REST/SSE/Event` | `v1` | `{FR-001}` | `{역할}` | `Draft/Approved` |

> 발주사 기존 시스템과의 인터페이스는 별도 행으로 잡고, **발주사 측 사양 원본(제공일·버전)**을 기록한다. 사양 미제공·변경은 지연 기록 대상이다.

## API 계약

| 항목 | 명세 |
|---|---|
| Method·Path | `{GET /api/...}` |
| 목적·권한 | `{행동 · 인증/인가 — 발주사 SSO·계정 체계}` |
| 요청 | `{headers, path, query, body schema}` |
| 성공 응답 | `{status · schema · 예시}` |
| 오류 응답 | `{status · code · 사용자/운영 메시지}` |
| timeout·retry | `{초 · 재시도 주체·횟수·backoff}` |
| idempotency | `{key·중복 결과}` |
| pagination·rate limit | `{규칙}` |
| 관측 | `{metric·log·trace, PII 제외 — 발주사 로그 정책 준수}` |

## 오류·상태 계약

| 조건 | HTTP·오류 코드 | 재시도 가능 | 사용자 표시 | 운영 대응 | 테스트 ID |
|---|---|---|---|---|---|
| `{검증 실패}` | `{400 / CODE}` | `아니오` | `{다음 행동}` | `{로그 수준}` | `{TC}` |
| `{권한 없음}` | `{403 / CODE}` | `아니오` | `{안내}` | `{감사 로그}` | `{TC}` |
| `{연동 시스템 timeout}` | `{504 / CODE}` | `{예}` | `{복구}` | `{알림·발주사 창구}` | `{TC}` |

## 데이터·스키마 계약 → ERD·테이블정의서

| Entity·Event | 필드 | 타입·형식 | 필수·nullable | 의미·단위 | 민감도 | 검증·기본값 | Owner |
|---|---|---|---|---|---|---|---|
| `{Entity}` | `{field}` | `{type}` | `{규칙}` | `{현업 용어 기준 정의}` | `{PII/일반}` | `{규칙}` | `{서비스}` |

> 공통코드(상태값·구분값)는 코드정의서 납품 대상이다 — 발주사 기존 코드 체계와의 매핑을 명시한다.

## 저장·무결성·생명주기

| 데이터 | 단일 Owner | 무결성·트랜잭션 | 인덱스·쿼리 | 보존·삭제 | 마이그레이션 | 롤백 |
|---|---|---|---|---|---|---|
| `{데이터}` | `{서비스}` | `{제약}` | `{패턴}` | `{정책 — 발주사 보존 규정 근거}` | `{forward/backfill — 현행 데이터 이관 포함 여부는 계약 확인}` | `{절차}` |

> [!WARNING] 데이터 이관은 대표적인 "당연히 포함인 줄 알았다" 항목
> 현행 시스템 데이터 이관이 계약 범위인지 착수 전에 확인한다. 범위 밖이면 OUT으로 명시하고, 요청이 오면 CR 회부.

## 호환·변경 정책

| 변경 | 호환성 | 소비자 영향 | 전환·deprecation | 검증 | 승인자 |
|---|---|---|---|---|---|
| `{필드 추가·삭제·의미 변경}` | `호환/비호환` | `{영향 — 발주사 연동 시스템 포함}` | `{dual read/write·기한}` | `{contract test}` | `{이름}` |

## 생산자·소비자 승인

- 생산자 확인: `{역할·이름·날짜}`
- 소비자 확인: `{역할·이름·날짜}`
- 발주사 연동 담당 확인: `{해당 시 — 인터페이스 사양 합의 근거}`
- Database 확인: `{해당 시}`
- QA contract test: `{명령·결과 위치}`
- API정의서·ERD 납품본 기준 버전: `{이 문서의 어느 버전을 어느 마일스톤에 제출하는가}`
- 미결·예외: `{없음 또는 Owner·기한}`

## 관련 문서

- [[API-명세-템플릿]]
- [[데이터-모델-템플릿]]
- [[외주 개발 산출물]]
- [[03_비기능 요구·실패 설계]]