API Compatibility Policy

API 호환성 정책

목적

이 문서는 MSA 분리 이후 Web Front service가 ClarusIubar/JamIssue_admin API를 소비할 때 지켜야 하는 consumer-side 기준을 정의합니다.

API contract의 provider-side 정본은 ClarusIubar/JamIssue_admin입니다. 이 레포는 contract를 구현하지 않고, 문서화된 contract를 소비합니다.

Web Front service가 소유하는 것

• API base URL 주입
• API client 호출 위치
• request payload 생성
• response DTO 기대 타입
• response parsing
• loading, empty, error UI 상태
• 로그인 진입과 callback 이후 화면 전환
• Web smoke와 consumer-side regression test

Web Front service가 소유하지 않는 것

• endpoint 동작 정의
• auth/session 발급 규칙
• DB schema
• storage policy
• service-role 작업
• provider-side contract test
• Worker runtime secret

호환성 원칙

ClarusIubar/JamIssue_admin API 변경은 기본적으로 additive change여야 합니다.

Web Front service 기준에서 breaking change로 보는 항목은 다음과 같습니다.

• 기존 response field 제거
• 기존 field 이름 변경
• field type 변경
• success/error status code 변경
• error response shape 변경
• auth/session 동작 변경
• OAuth callback path 변경
• pagination cursor 형식 변경

breaking change가 필요한 경우 ClarusIubar/JamIssue_admin 이슈와 PR에서 Web Front 영향도를 기록하고, 이 레포의 수정 PR과 함께 검증해야 합니다.

Web Front PR 체크리스트

API 소비 방식이 바뀌는 PR은 다음을 확인합니다.

• 사용하는 endpoint 목록 기록
• required/optional field 구분 확인
• empty state 응답 확인
• anonymous/authenticated 상태 차이 확인
• npm run typecheck 통과
• npm run smoke:public 통과
• 필요한 경우 ClarusIubar/JamIssue_admin contract issue/PR 링크 첨부

운영 API 기준값

• 운영 API base URL: https://api.daejeon.jamissue.com
• Web Front public env: PUBLIC_APP_BASE_URL

모바일 앱 실기기 테스트는 별도 서비스의 검증 단계입니다. 이 위키는 Web Front service 기준을 다룹니다.