공공 OpenAPI 는 자체 BFF 로 한 번 감싼다

공공기관·외부 사업자가 제공하는 OpenAPI 를 프론트엔드에서 직접 호출 하면 첫 화면은 빠르게 만들 수 있습니다. 그러나 운영을 며칠 굴려 보면 같은 자리에서 같은 종류의 사고가 반복됩니다 — 키 노출, 응답 코드 해석, 프로토콜 미스매치. 그래서 외부 API 는 우리쪽 BFF 한 겹 을 사이에 두는 게 거의 항상 옳습니다.

1. 직접 호출이 만드는 4 가지 사고

사고 유형	직접 호출에서 발생	BFF 한 겹의 효과
인증키 노출	클라 번들에 serviceKey 포함 → public secret 됨	서버 환경변수, 클라는 접근 불가
응답 코드 해석	HTTP 200 인데 resultCode=90 빈 응답 → 화면이 조용히 빈 카드	BFF 가 200 + resultCode≠0 을 5xx 로 정규화
프로토콜 미스매치	"공식 가이드는 https" 인데 실제는 http 만 동작	BFF 가 http 호출 + 클라에는 https 만 노출
응답 스키마 불안정	외부가 필드명을 camelCase ↔ snake_case 로 바꾸면 클라 깨짐	BFF 가 한 형태로 정규화

2. 가장 흔한 함정 — 키 전파 지연

공공 API 는 활용 신청이 승인 돼도 인증키가 게이트웨이에 전파되기까지 시차가 있습니다. 같은 키로 데이터셋 A 는 즉시 동작하고 데이터셋 B 는 한 시간 뒤에 동작하는 일이 흔합니다. 직접 호출이라면 "신규 데이터셋 출시일에 화면이 빈 카드" 가 됩니다. BFF 가 있으면:

[Client] ──▶ [BFF /api/x]
                │
                ▼
       resultCode 검증
                │
       ┌────────┴────────┐
       ▼                 ▼
   정상 → 변환·캐시   90 → "준비 중" 명시

"준비 중" 을 명시 하는 것이 화면을 비우는 것보다 훨씬 안정적입니다.

3. BFF 가 책임지는 5 가지

1. 키 보관 — 환경변수 한 곳. 로테이션도 한 곳.
2. 응답 코드 정규화 — 외부의 resultCode/status/code 를 HTTP status 또는 일관된 {ok, data, error} 로.
3. 프로토콜 정규화 — http only · 자체 호스팅 · 표준 게이트웨이 등 외부의 변덕을 BFF 가 흡수.
4. 캐시 정책 — 같은 키워드 1초에 10번 들어와도 외부에는 한 번. Cache-Control 헤더는 BFF 가 적습니다.
5. 레거시 호환 — 외부가 v1 → v2 로 갈아탈 때 BFF 만 바꾸면 클라는 무중단.

4. 적용 전 / 적용 후

측면	직접 호출	BFF 한 겹
키 위치	클라 번들 (노출)	서버 env (격리)
새 데이터셋 첫날	빈 카드 / 콘솔 에러	"준비 중" 라벨
외부 다운	화면 다운	마지막 캐시 또는 명시 메시지
외부 응답 변경	코드 곳곳 수정	BFF 한 파일
호출 빈도 제어	클라마다	BFF 한 곳

5. 자신의 프로젝트에 적용하려면

• 클라가 외부 도메인을 직접 호출하는 자리를 모두 찾는다 (fetch('https://外部') grep).
• 각 호출 자리마다 /api/x BFF 한 줄을 만든다 — proxy + 정규화 + cache header.
• 외부의 응답 코드를 HTTP status 또는 {ok,error} 한 가지 형태로 정리한다.
• .env.* 에 키를 옮기고 클라 코드의 키를 삭제 한다.
• 신규 데이터셋 도입 시 BFF 의 "준비 중" 분기를 기본값 으로 두고 동작 확인 후 정상화.

외부 API 는 우리 통제 밖이지만, 그 변덕을 어디서 흡수할지 는 우리 결정. BFF 한 겹이 그 결정의 자리입니다.