API contracts

Source of truth

• Repository: prego-zuplo
• Typical locations: docs/openapi/*.oas.json (fragments), merged output used for portal/config (see that repo’s README and scripts/).
• CI / local checks: In prego-zuplo, GitHub Actions runs pnpm run verify:portal (verify + Zudoku docs production build). After config/*.oas.json changes, run pnpm run sync-oas then pnpm run verify from that repo’s root; use verify:portal for the same run as CI. See How to add an API §1.

Consumption

• Zuplo deploys routes and policies aligned with the merged spec.
• Browser callers: CORS Access-Control-Allow-Headers (e.g. optional x-trace-id for funnel correlation) and Portal ALLOWED_ORIGINS are gateway policy in prego-zuplo, not defined by the OAS JSON alone. See Tenant & trust boundaries and prego-zuplo runbook README (index) · folder.
• Generated SDKs (if used) should be produced from the same merged artifact as production.
• This docs site describes process in How to add an API; it does not duplicate the JSON sources.

Versioning

• Prefer explicit path versions (/v1/, /v2/) for breaking changes.
• Keep a short changelog in prego-zuplo (e.g. docs/ or CHANGELOG.md) when operations are added, deprecated, or removed.

Related

• Master plan §10
• Dependency inspection
• Repository README index — includes prego-zuplo OpenAPI folder links
• Tenant & trust boundaries — optional x-trace-id shape; prego-zuplo runbook README (index) · folder

---

한국어

공개 API 계약의 원천은 prego-zuplo 저장소의 OpenAPI 입니다. 병합·검증 스크립트는 해당 레포를 따르며, 이 페이지는 절차와 링크만 제공합니다. config/*.oas.json 변경 후 루트에서 pnpm run sync-oas → pnpm run verify; GitHub CI와 동일 검증은 pnpm run verify:portal입니다. 자세한 절차는 API 추가 방법 §1을 봅니다. 브라우저 CORS·ALLOWED_ORIGINS·선택적 x-trace-id 는 게이트웨이 정책이며 테넌트 신뢰 경계와 prego-zuplo README (색인) · docs/runbook/ 을 참고합니다.