External API

Route Handler 외부 API 보호

클라이언트가 외부 서비스 키를 직접 들고 있지 않도록 서버 라우트에서 fetch와 응답 가공을 처리합니다.

서버 호출

fetch API 프록시 경계

Route Handler 안에서 외부 서비스 요청을 만들고 인증 헤더, query, 응답 가공을 서버 책임으로 둡니다.

비밀 값

환경 변수 서버 보관

API 키와 base URL을 서버 전용 값으로 관리해 브라우저 번들에 외부 서비스 권한이 노출되지 않게 합니다.

실패 계약

오류 응답 표준화

외부 API 실패를 상태 코드, 내부 오류 코드, 사용자 메시지로 나눠 클라이언트가 처리하기 쉽게 반환합니다.

호출 경계

클라이언트 내부 API 경유

브라우저는 내부 API 라우트만 호출하고 서버가 인증, 속도 제한, 외부 요청을 대신 처리합니다.

서버 프록시

API 키는 서버 환경 변수에 남깁니다

날씨 API처럼 키가 필요한 요청은 클라이언트 대신 Route Handler가 호출하는 구조가 적합합니다.

통합 흐름

환경 변수preview와 production 키를 구분해 테스트 호출이 실제 운영 계정을 쓰지 않게 합니다.
오류 응답timeout, 4xx, 5xx, 파싱 실패를 다른 상태로 돌려 재시도 여부를 판단하게 합니다.
클라이언트 호출브라우저에는 내부 엔드포인트와 화면용 데이터만 노출하고 원본 응답은 서버에서 정리합니다.