바이브코딩 강의 5편 — API, 남이 만든 기능을 주문해서 갖다 쓰는 법 (요청·응답·API 키·토큰 요금)

내가 처음부터 다 만들지 않아도 된다. 남이 이미 만들어 둔 기능을 정해진 창구로 빌려 쓰는 것, 그게 API다.

이 글 3줄 요약

• API는 남의 서비스 기능을 정해진 창구로 빌려 쓰는 것이다. 식당에서 주방에 안 들어가고 메뉴판에 있는 걸 주문하면 음식이 오듯, 상대 코드를 몰라도 요청만 보내면 결과가 온다.
• 한 번의 주문은 요청과 응답의 왕복이다. 요청은 내가 보내는 주문서, 응답은 돌아오는 서빙. 이 왕복 한 번이 API 한 번이고, 프로그램은 이걸 자동으로 수백 번 돌린다.
• API 키는 회원카드이자 내 지갑이라 절대 노출 금지, 요금은 토큰 기준 종량제라 쓴 만큼만 낸다. 이 두 가지만 지키면 사고 안 난다.

이 글은 AI 바이브코딩 강의 12부작 시리즈의 5편이다. 시리즈 전체 지도와 바이브코딩이 뭔지는 1편에서 다룬다. 오늘은 그중 네 번째 주제, 프로그램끼리 대화하는 법인 API를 잡는다.

오늘의 질문 — 남이 만든 기능을 내 것에 어떻게 가져오나

프로그램을 만들다 보면 곧바로 벽에 부딪힌다. 네이버 지도를 화면에 띄우고 싶고, 카톡으로 알림을 보내고 싶고, 실시간 환율을 가져오고 싶고, 긴 글을 AI가 요약해줬으면 한다. 그런데 이걸 다 내가 만들어야 하나? 지도를 직접 그리고, 환율을 매일 손으로 받아적고, 요약하는 AI를 처음부터 학습시켜야 하나?

아니다. 답은 API다. API(에이피아이 = 프로그램끼리 약속된 주문 창구)는 이미 있는 서비스에 이것 좀 해달라고 요청하면 결과를 받아오는 방법이다. 지도를 내가 만들 필요도, 환율을 손으로 받아적을 필요도 없다. 오늘은 그 요청과 응답, 그리고 요금이 어떻게 도는지만 이해하면 된다. 딱 그 정도가 실전에서 필요한 전부다.

API = 식당의 주문 창구

API를 한 문장으로 잡으려면 식당을 떠올리는 게 제일 빠르다. 손님은 주방에 직접 들어가지 않는다. 메뉴판에 있는 것만, 정해진 방식으로 주문한다. API도 똑같다. 남의 서비스 내부는 안 건드리고, 그 서비스가 열어둔 메뉴, 즉 기능만 요청한다.

여기서 세 가지가 자연스럽게 따라온다.

• 메뉴판은 그 서비스가 열어둔 기능 목록이다. 검색해줘, 번역해줘, 환율 알려줘, 이 글 요약해줘 같이 서비스마다 주문 가능한 메뉴가 정해져 있다. 메뉴판에 없는 건 주문할 수 없다.
• 주방이 어떻게 만드는지는 몰라도 된다. 불 세기나 레시피는 식당 사정이다. 나는 주문하고 결과인 음식만 받으면 된다. API를 쓸 때 상대 회사의 코드를 한 줄도 몰라도 되는 이유가 이것이다.
• 정해진 방식으로만 주문한다. 메뉴판 밖의 요청, 이상한 방식의 주문은 통하지 않는다. 창구에는 약속된 규칙이 있다.

이 감각 하나면 API의 본질은 잡힌 것이다. 내가 다 만드는 게 아니라, 남이 완성해 열어둔 창구에 주문한다.

한 번의 주문 = 요청 + 응답

주문 창구가 실제로 어떻게 도는지 보면, 딱 왕복 한 번이다. 주문서를 보내면 서빙으로 돌아온다.

여기서 두 단어만 챙기면 된다. 요청(Request)은 내가 보내는 주문서다. 응답(Response)은 돌아오는 서빙이다. 이 왕복 한 번이 API 한 번이다.

사람이 주문하는 것과 다른 점은 딱 하나, 손으로 하는 게 아니라는 것이다. 코드가 대신 주문서를 쓰고 대신 받아온다. 그래서 프로그램은 이 왕복을 1초에 수백 번도 자동으로 돌린다. 앞 강의에서 만든 자동화가 이 왕복을 쉬지 않고 반복하는 것일 뿐이다.

API 키 = 식당 회원카드이자 내 지갑

창구에 주문을 넣을 때 빠지면 안 되는 게 하나 있다. 누가 주문했는지 증명하는 카드, API 키다. API 키(key = 서비스가 나에게 발급한 길고 고유한 문자열)를 주문서에 같이 붙여 보낸다. 이 카드가 없으면 창구에서 회원 아니시네요 하며 주문을 거절한다.

이 카드가 중요한 진짜 이유는 요금 때문이다. 회원카드로 긁으면 그 사람 계좌로 청구되듯, 내 키로 부른 API 요금은 전부 내 앞으로 계산된다. 그래서 API 키는 단순한 출입증이 아니라 곧 내 지갑이다.

여기서 이 강의에서 가장 중요한 안전 규칙이 나온다. 키는 절대 남에게 보이면 안 된다. 유출되면 남이 내 카드로 주문해 내 돈으로 결제한다. 코드에 그대로 박아두거나 화면에 노출하지 않는 게 철칙이다. 안전하게 보관하는 구체적인 방법은 뒤쪽 보안과 비용 편에서 따로 다룬다. 지금은 키 = 내 지갑, 노출 금지, 이 감각만 몸에 붙이면 된다.

토큰 = 글자 수로 재는 종량제 요금

그럼 요금은 어떻게 매겨질까. 답은 종량제, 쓴 만큼 내는 방식이다. 계량기 눈금 역할을 하는 게 토큰이다.

토큰(token = AI가 글을 처리하는 최소 조각, 한글은 대략 한 글자가 한 토큰 안팎)이 곧 계량기 눈금이다. 짧게 물으면 눈금이 조금 오르고, 길게 물으면 많이 오른다. 여기서 놓치기 쉬운 게 하나 있는데, 보낸 글과 받은 글을 둘 다 계산한다는 것이다. 수도요금처럼 내가 보낸 질문 길이에 AI가 돌려준 답 길이를 합쳐 토큰으로 환산하고, 토큰당 정해진 단가로 요금이 붙는다.

그래서 요청 한 번은 대개 몇 원 수준이다. 전기나 수도처럼 한 번 켤 때마다 얼마라 감이 잘 안 오지만, 짧은 요청은 1원 안팎이다. 문제는 자동으로 수천 번 돌 때다. 한 번은 티끌이지만 쌓이면 무시 못 한다. 자동화가 밤새 폭주해 요금이 튀는 사고를 막는 법 역시 보안과 비용 편에서 다룬다.

실전 예시 — 매일 아침 뉴스 요약이 저절로 오는 구조

말로만 들으면 막연하니 실제로 도는 구조 하나를 뜯어보자. 매일 아침 눈 뜨면 오늘 뉴스 요약 리포트가 메일이나 카톡에 와 있는 자동 리포트다.

여기서 핵심은, 새 서비스를 만든 게 아니라는 것이다. 뉴스 API와 AI 요약 API, 남이 만든 기능 둘을 이어붙였을 뿐이다. 네이버 검색 API나 카카오 알림처럼 이미 있는 걸 빌려 쓰는 감각이 전부다. 앞에서 배운 요청과 응답의 왕복이 두 번 일어난 것이고, 그 앞뒤로 예약 실행과 알림 발송이 붙었을 뿐이다.

비용도 부담이 없다. 요청 한 번에 몇 원 수준이라, 하루 한 번이면 한 달에 커피값도 안 나온다. 여기서 종량제의 이점이 분명해진다. 월 구독은 안 써도 정액이 빠지지만, API 종량제는 부른 만큼만 낸다. 가끔 쓰는 기능이라면 종량제가 압도적으로 싸다. 안 부르면 0원이니까.

REST = 주소로 가리키고, 동사로 행동하는 약속

주문에도 표준 규칙이 있다. 가장 널리 쓰는 게 REST(레스트, 웹에서 가장 널리 쓰는 API 주문 규칙)다. 겁먹을 필요 없이 두 조각이면 끝난다.

• 주소(URL)로 무엇을 가리킨다. 가게 안 물건마다 자리가 있듯, 자원 즉 데이터마다 고유 주소가 있다. 그 주소를 대면 이걸 말하는 거야가 정해진다. 예를 들어 주소 끝에 orders/128 이 붙으면 128번 주문을 가리킨다.
• 동사로 어떻게 할지 정한다. 같은 주소라도 무슨 행동인지는 동사로 정한다. 가져와서 조회하는 건 GET, 새로 등록하는 건 POST다. 조회냐 등록이냐가 헷갈리지 않게 하는 약속이다.

딱 여기까지면 충분하다. 주소 더하기 동사로 주문한다, 이 한 줄이면 실전에서 안 막힌다. REST를 더 깊이 팔 필요는 지금 없다. AI에게 이 API GET으로 불러줘 정도만 말할 수 있으면 된다.

흔한 오해 두 가지

API를 처음 만나면 거의 모두가 하는 오해가 둘 있다. 미리 짚고 가면 헤매지 않는다.

첫 번째 오해에 빠지면 지도, 번역, 결제, AI를 손수 만들려다 시작도 못 하고 지친다. 바퀴를 다시 발명할 필요가 없다. 남이 완성한 걸 창구로 주문하면 그만이다.

두 번째 오해는 더 위험하다. 키를 코드에 박고 그 코드를 그대로 인터넷, 특히 깃허브에 올렸다가 요금 폭탄을 맞는 사고가 진짜 흔하다. 유출되면 남이 내 돈으로 API를 부른다. 그래서 키는 반드시 따로 숨겨서 보관한다.

3줄 정리 — 오늘 가져갈 것

딱 세 줄만 챙기면 이번 강의는 성공이다.

• API = 남의 기능을 빌려 쓰는 주문 창구. 주방인 상대 코드는 몰라도 된다. 메뉴인 요청을 보내면 음식인 응답이 온다. 요청과 응답의 왕복이 API 한 번이다.
• API 키 = 회원카드 = 내 지갑. 누가 썼는지 증명하고 요금 청구 대상이 된다. 그래서 절대 노출 금지다.
• 요금은 토큰 기준 종량제, 쓴 만큼. 보낸 글과 받은 글로 계산한다. 한 번은 몇 원이라도 자동으로 많이 돌면 쌓인다.

오늘 배운 단어 네 개는 요청, 응답, API 키, 토큰이다. 이 넷이 나올 때마다 아, 주문과 서빙과 회원카드와 수도요금 하고 떠오르면 이번 강의는 몸에 붙은 것이다.

다음 편 — 바이브코딩 강의 6편. API로 받아온 결과를 어디에 쌓아둘지, 파일과 데이터베이스의 차이부터 표를 읽는 법까지 데이터 저장을 다룬다.