2.5 KiB
KBX API Contract Governance v14
1. 목적
API Route, Method, Permission, 성공 Status, Idempotency와 Error discriminator가 Frontend/Backend에서 독립적으로 변하는 문제를 막는다.
2. Source of Truth
contracts/api/kbx.api.json
Operation은 최소 다음을 가진다.
id
method
path
permission
kind
idempotency
successStatuses
source는 Reference Foundation의 FastEndpoint 위치를 추적하기 위한 정보다.
3. 생성물
contracts/api/kbx.api.json
↓
generated/api-manifest.json
↓
packages/kbx-contracts/src/generated/apiCatalog.ts
backend/Shared/Contracts/Generated/KbxApiCatalog.g.cs
contracts/api/openapi.kbx.json
Source SHA가 TS/C# Catalog에서 일치해야 한다.
4. Web 사용법
업무 모듈은 다음을 직접 사용하지 않는다.
axios
fetch
'/api/...'
대신:
kbxApi.request<OrderSearchResponse>(
'oms.orders.search',
{ query: filter },
)
화면이 URL과 HTTP Method를 소유하지 않게 한다.
5. Idempotency
none
supported
required
required Operation은 안정적인 Idempotency Key 없이 Client가 호출할 수 없다.
중요: Retry할 때는 새 Key를 생성하지 않고 최초 Key를 재사용한다.
6. FastEndpoints parity
validate-api-governance.mjs는 Backend의 실제:
Get/Post/Put/Patch/Delete
Route
Permissions(...)
을 스캔하고 Contract와 양방향 비교한다.
- Backend에만 존재 → FAIL
- Contract에만 존재 → FAIL
- Permission 불일치 → FAIL
7. OpenAPI
KbxApiContractOperationFilter는 실제 Swashbuckle 문서에 다음을 추가한다.
operationId
x-kbx-permission
x-kbx-idempotency
x-kbx-kind
KbxProblemOpenApiOperationFilter는 표준 Problem response family를 노출한다.
8. DTO Shape 검증
Reference Foundation에는 실행 가능한 .NET Host/Solution이 없으므로 실제 Request/Response Property Schema 비교는 여기서 통과했다고 간주하지 않는다.
Host Repository에서는 실제 Swashbuckle OpenAPI를 생성하고 validate-live-openapi.mjs를 Mandatory Gate로 사용한다.
이는 Contract 이름만 비교하고 실제 DTO Shape drift를 놓치는 것을 방지하기 위한 2단계 검증이다.
9. 금지
- Screen에서 Route 문자열 작성
- Screen마다 Axios Error parsing
- LLM이 임의 API URL 생성
- POST 실패를 무조건 자동 Retry
- Idempotency가 없는 강한 Mutation 자동 Retry
- 404/403을 화면마다 서로 다른 문구로 해석