API 기본기 정리: REST·HTTP·인증과 LLM API를 12분에 이해하기

핵심 메시지

• API는 클라이언트와 서버 사이의 '계약'으로, 무엇을 요청할 수 있고 어떻게 요청하며 무엇을 돌려받는지를 정의한다.
• 모든 API 호출은 HTTP 위에서 동사(GET·POST·PUT·DELETE), 엔드포인트, 헤더, 본문으로 이뤄진다.
• REST·웹훅·GraphQL·스트리밍 등 패턴에 따라 데이터를 주고받는 방식이 달라진다.
• 인증은 API 키·OAuth·베어러 토큰으로 나뉘며, 키를 소스코드에 하드코딩하지 말고 환경변수로 관리해야 한다.
• LLM API는 같은 HTTP 기반이지만 토큰·스트리밍·속도 제한이라는 추가 개념을 이해해야 한다.

쉽게 이해하기

발표자는 API를 레스토랑에 비유한다. 손님이 클라이언트, 주방이 서버, 웨이터가 API다. 손님은 주방에 들어가 직접 음식을 만들지 않고 웨이터에게 주문(요청)을 건네면 웨이터가 결과(응답)를 가져다준다. 주방이 어떻게 요리하는지 몰라도 웨이터에게 말하는 법만 알면 된다. 스포티파이가 1초도 안 되어 추천 재생목록을 보여주는 것도, 앱이 API로 추천 서비스에 요청해 실시간으로 데이터를 받아오기 때문이다.

모든 API 호출은 브라우저가 웹페이지를 불러올 때와 같은 HTTP 위에서 이뤄진다. 알아야 할 네 가지는 동사, 엔드포인트, 헤더, 본문이다. 동사는 GET(조회)·POST(생성)·PUT(수정)·DELETE(삭제)를 뜻하고, 엔드포인트는 자원의 주소인 URL이다. 헤더는 인증 토큰·콘텐츠 타입·속도 제한 정보가 오가는 메타데이터이고, 본문은 POST·PUT에서 실제로 보내는 데이터다. 서버는 상태 코드로 답한다. 200은 성공, 201은 생성, 401은 미인증, 404는 자원 없음, 500은 서버 오류다.

API에는 몇 가지 아키텍처 패턴이 있다. 가장 흔한 REST는 프로토콜이 아니라 관례의 모음으로, 자원을 URL의 명사로 두고 알맞은 동사를 쓰며 JSON으로 응답하고 무상태다. 공개 API의 약 90%가 이 방식이다. 웹훅은 모델을 뒤집어 앱이 API를 부르는 대신 API가 앱을 호출한다. 스트라이프는 결제가 완료되면 당신 서버로 POST 요청을 보낸다. GraphQL은 여러 엔드포인트 대신 하나의 엔드포인트에 원하는 데이터의 모양을 쿼리로 보내 과다·과소 페치를 없앤다. 스트리밍은 전체 응답을 기다리지 않고 준비되는 대로 청크로 보내는데, LLM이 답을 한 단어씩 출력하는 것이 바로 이 방식이다.

인증은 API가 당신이 누구인지 아는 방법이다. 가장 단순한 API 키는 헤더나 URL에 넣는 고유 문자열로, 유출되면 남이 당신 이름으로 호출하고 요금은 당신이 낸다. 그래서 스크립트·노트북·깃허브 어디에도 키를 하드코딩하지 말고 .env 파일과 dotenv로 환경변수로 관리해야 한다. 더 복잡한 경우에는 OAuth를 쓴다. '구글로 로그인'처럼 비밀번호를 넘기는 대신 특정 권한만 위임하는 방식으로 만료 토큰·리프레시·스코프가 관여한다. 정리하면 서버 간 호출엔 API 키, 사용자 권한 위임엔 OAuth, 베어러 토큰은 둘 중 하나를 인증 헤더에 담는 형식이다.

LLM API도 같은 HTTP 기본기를 따르지만 요청의 모양이 조금 다르다. 첫째, LLM은 단어가 아니라 토큰 단위로 처리하고 과금하며 컨텍스트 윈도우도 토큰으로 측정된다. 둘째, 응답이 길 수 있어 생성하는 대로 토큰을 돌려주는 스트리밍으로 점진적으로 표시해 반응성을 확보한다. 셋째, 분당 보낼 수 있는 토큰에 속도 제한이 있어 프로덕션에서는 재시도, 지수 백오프, 때로는 큐가 필요하다. 앤트로픽과 오픈AI SDK가 HTTP 계층을 감싸주지만 그 아래는 앞서 살펴본 것과 같은 구조다.

주요 인사이트

• 현대 AI 앱이 어떻게 동작하는지 이해하려면 결국 API를 이해해야 한다. 역할과 무관하게 모든 엔지니어의 필수 지식이다.
• REST는 프로토콜이 아니라 관례의 모음이며, 예측 가능하고 무상태라는 점이 널리 쓰이는 이유다.
• 웹훅은 '요청-응답'을 뒤집어 이벤트 기반 아키텍처를 가장 단순한 형태로 구현한다.
• LLM 인터페이스가 반응성 있게 느껴지는 이유는 스트리밍으로 토큰을 즉시 흘려보내기 때문이다.
• API 호출의 구조(동사·엔드포인트·헤더·본문·상태 코드)만 읽을 줄 알면 어떤 API도 디버깅할 수 있다.

자주 묻는 질문

관련 AI 소식