콘텐츠로 이동

API 공통 응답 계약 정책

문서 역할

  • 역할: 규범
  • 문서 종류: policy
  • 충돌 시 우선 문서: 공통 JSON API 응답 envelope은 이 문서, 실패 ErrorData/taxonomy는 api-error-contract-policy.md
  • 기준 성격: as-is

목적

API/Admin/Mobile이 JSON API 성공/실패를 같은 envelope 기준으로 판정하게 하고, 성공 DTO 기준과 실패 에러 taxonomy 기준을 섞지 않는다.

적용 범위

  • coupler-api
  • coupler-admin-web
  • coupler-mobile-app
  • Swagger/OpenAPI에서 문서화하는 JSON API 응답 경계

제외 범위:

  • 파일 스트리밍
  • proxy pass-through
  • 네트워크/protocol 실패

단일 SoT

현재 진입점

  • API 성공 응답: coupler-api/controller/common.ts의 response_success(res, data)
  • API 실패 응답: coupler-api/controller/common.ts의 response_error(res, descriptor, context?)
  • 공통 계약 산출물: operation별 성공 data 타입은 coupler-api/packages/contracts/src/generated/apiContract.ts에서 생성하고, 공통 envelope 타입과 runtime guard는 coupler-api/packages/contracts/src/response.ts에 둔다. Runtime guard는 envelope과 실패 ErrorData만 검증하고 성공 data는 unknown으로 유지한다. Admin/Mobile은 publish된 @coupler-developer/coupler-api-contracts package를 설치하고 lockfile로 고정한다.
  • Mobile 응답 경계: coupler-mobile-app/src/api/client.ts, coupler-mobile-app/src/api/apiResponse.ts, coupler-mobile-app/src/utils/APIUtils.ts
  • Admin 응답 경계: coupler-admin-web/src/api/apiResponse.ts, coupler-admin-web/src/api/adminListClient.ts, coupler-admin-web/src/app.tsx

필수 규칙

  • 계약된 JSON API 성공은 HTTP 200의 { ok: true, data }로 반환한다.
  • 계약된 JSON API 실패는 HTTP 200의 { ok: false, error: ErrorData }로 반환한다.
  • ok는 JSON body의 성공/실패 1차 판정값이다.
  • 성공 data는 operation별 성공 DTO만 담는다.
  • 실패 error는 API 에러 계약 정책의 ErrorData만 담는다.
  • 성공 응답에는 error를 넣지 않고, 실패 응답에는 성공 data를 넣지 않는다.
  • 성공 본문이 없으면 data: null을 사용한다. undefined 성공 payload는 공통 응답 계약으로 보지 않는다.
  • HTTP 4xx/5xx는 JSON API ErrorData taxonomy가 아니라 transport/protocol/proxy 실패에만 사용한다.
  • Mobile/Admin은 단일 package response runtime으로 envelope을 검증하고 ok로 직접 분기한다. isSuccess*/isFailure* 같은 branch별 envelope helper를 추가하지 않는다. 실패 세부 처리는 서버에서 생성한 error runtime contract와 API 에러 계약 정책을 따른다.
  • Operation별 성공 DTO generic은 runtime 검증 결과가 아니라 compile-time 계약이다. DTO runtime validator가 없는 경계에서는 JSON parse와 envelope 검증을 data: unknown으로 끝내고, 정적 DTO 결합은 공통 request boundary 한 곳으로 제한한다.
  • result_code, result_msg, legacy numeric code, display message 문자열, top-level domain status를 공통 envelope 판정값으로 쓰지 않는다.
  • dual parser, legacy envelope branch, transition helper, 제거 조건 없는 호환 필드는 최종 공통 응답 계약에 둘 수 없다.

예외

  • Admin 목록 endpoint는 예외 없이 공통 envelope을 사용하며 DataTables success body를 반환하지 않는다.
  • 파일 스트리밍, proxy pass-through, 네트워크/protocol 실패는 ErrorData, error_code, error_action을 만들거나 product flow 분기 기준으로 쓰지 않는다.

검증 기준

  • 공통 response writer, package response runtime, Mobile/Admin request boundary가 같은 envelope을 가리키는지 확인한다.
  • Package public response/envelope 타입은 failure branch에서 strict ErrorData를 사용해야 한다. Runtime guard는 검증하지 않은 operation별 성공 DTO를 타입으로 단정하지 않고 ApiEnvelope<unknown>만 보장한다. Swagger success map 생성을 위해 남아 있는 generated 내부 helper 타입은 package public response 기준으로 보지 않는다.
  • Package response entrypoint의 public runtime allowlist는 isApiEnvelope 하나다. Admin/Mobile facade는 로직 없는 isEnvelope 연결 하나만 허용하며 다른 envelope validator나 branch helper를 추가하지 않는다.
  • Swagger/OpenAPI success schema가 없거나 느슨하면 generated success data type은 unknown 또는 loose object가 될 수 있다. generated artifact만으로 전체 success DTO 완성 증거로 해석하지 않는다.
  • CI와 문서 검증은 현재 공통 응답 구조의 금지 조건과 참조 정합성을 확인한다. 과거 legacy helper 이름이나 임시 구현명 자체를 검증 기준으로 삼지 않는다.
  • 공통 envelope 변경의 하위 호환과 cutover 판정은 엔지니어링 가드레일의 API 계약과 runtime-state 안전성의 독립 판정을 따른다. 제거 예정 dual parser·legacy envelope branch가 필요하면 API cutover: Yes이며, Store 강제 업데이트나 NextPush mandatory만으로 이전 소비자의 current-API case를 증명하지 않는다.

체크리스트

  • [ ] JSON API 성공이 { ok: true, data }로 반환되는가?
  • [ ] JSON API 실패가 { ok: false, error: ErrorData }로 반환되는가?
  • [ ] 클라이언트가 ok로 먼저 성공/실패를 분기하는가?
  • [ ] 성공 DTO와 실패 ErrorData가 한 응답에 섞이지 않는가?
  • [ ] Admin 목록 endpoint에 non-envelope success body가 남아 있지 않은가?
  • [ ] HTTP non-2xx와 ErrorData taxonomy가 섞이지 않는가?
  • [ ] transition/legacy/dual parser/helper가 최종 계약에 남아 있지 않은가?
  • [ ] Package와 소비자 facade의 envelope runtime export가 폐쇄형 allowlist를 벗어나지 않는가?
  • [ ] Swagger/OpenAPI, generated contract/package artifact, Mobile/Admin boundary, 정책 문서가 같은 envelope 기준을 가리키는가?

관련 문서