24장. API는 채팅창을 제품 기능으로 연결하는 계약이다

API를 쓰면 입력, 출력, 모델, 도구, 저장, 시간 제한, 재시도를 코드로 관리할 수 있다. 동시에 키 관리, 비용, 오류, 데이터 보존 책임이 생긴다. 클라이언트 브라우저나 앱 코드에 공급자 API 키를 넣지 않는다. 서버 환경 변수나 비밀 관리 시스템에서 읽는다.

OpenAI API 개요는 키를 브라우저·앱 같은 클라이언트 코드에 노출하지 말고 서버 환경 변수나 키 관리 시스템에서 읽도록 안내한다. 운영에서는 요청 ID도 기록해 실패를 추적한다.

이 책의 선택 예제는 모델명을 환경 변수로 받는다. 계정에서 사용할 수 있는 현재 모델을 공식 문서에서 확인한다.

cd /Users/honi/WithAI/books/ai-competence-bible
export OPENAI_API_KEY="여기에_실제_키를_문서나_Git에_쓰지_말고_로컬에서만_설정"
export OPENAI_MODEL="계정에서_사용_가능한_모델_ID"
node examples/openai-responses.mjs

예제는 store: false를 사용하지만 이것만으로 모든 보존 문제가 끝나는 것은 아니다. 기능별 저장과 남용 모니터링, 파일·도구·외부 MCP의 정책이 다를 수 있다. OpenAI 데이터 제어 문서처럼 공급자의 현재 공식 정책과 조직 계약을 확인한다.

API 래퍼는 공급자 차이를 내부 계약으로 감싼다.

const result = await provider.generate({
  task,
  documents,
  outputSchema,
  timeoutMs: 30_000,
  traceId
});

응답 원문을 무기한 저장하지 않는다. 필요한 메타데이터와 평가 결과, 마스킹된 오류를 목적과 보존 기간에 맞게 남긴다.

운영 API의 실패 계약

네트워크는 끊기고 모델은 제한에 걸리며 응답은 잘릴 수 있다. 인증 실패는 즉시 중단하고, 요청 제한은 서버 힌트를 반영한 제한된 backoff를 사용한다. timeout은 공급자가 요청을 받았는지 확인한 뒤 재시도한다. 외부 행동과 연결되었다면 중복 실행 여부부터 대사한다.

trace_id + provider_request_id + prompt_version + model_config + tool_version

이 식별자를 연결하되 Authorization 헤더와 원문 개인정보는 로그에 쓰지 않는다. fallback은 품질·데이터 정책·지역·도구가 사전 승인된 경로만 사용한다. 운영 전 429, 500, timeout, 잘린 JSON, 빈 응답을 fixture로 주입한다. 성공 경로만 시험한 API는 아직 제품 기능이 아니다.