API 연결: 요청·응답·API 키 초보 가이드

API 연결을 초보자 기준으로 정리했습니다. 요청, 처리, 응답, API 키, 서버 처리, 사용량 비용까지 바이브코딩으로 외부 기능을 붙일 때 필요한 기준을 설명합니다.

이 글은 Supabase 관련 작업 흐름을 바탕으로 정리한 글입니다.
도구 UI와 기능은 시점에 따라 달라질 수 있으니, 실제 적용 전에는 공식 문서와 현재 환경을 함께 확인하세요.

Table of Contents

바이브코딩으로 외부 기능을 붙일 때 가장 먼저 잡아야 할 감각

이 글을 읽으면 알 수 있는 것 3가지

API가 정확히 무엇인지 초보자 눈높이로 이해하는 법
GET, POST, API 키 같은 말이 왜 나오는지
외부 기능 연결이 꼬일 때 AI에게 어떻게 물어야 하는지
API 호출 비용과 비밀 키 관리를 처음부터 같이 봐야 하는 이유

바이브코딩으로 웹서비스를 만들다 보면 어느 순간 이런 말이 너무 자연스럽게 튀어나옵니다.
“이 API 연결해줘.”
“응답값 받아서 화면에 뿌려줘.”
“키는 서버에서 처리해.”

문제는 초보자 입장에서는 여기서부터 갑자기 공기가 바뀐다는 점입니다.
화면 만들기, 버튼 만들기까진 괜찮았는데, API가 나오면 갑자기 “개발자 영역”처럼 느껴집니다.

하지만 API는 생각보다 어렵지 않습니다.
핵심만 잡으면 결국 이것입니다.

요청을 보낸다 → 상대가 처리한다 → 결과를 돌려준다

이 흐름만 이해해도, 외부 기능을 붙일 때 훨씬 덜 겁이 납니다.

이 글의 역할: API 연결 보조 가이드

이 글은 바이브코딩 입문 대표 글이 아니라, 설계와 배포 사이에서 외부 연결 감각을 붙이는 보조 가이드입니다.
처음 읽는 순서는 아래처럼 두는 편이 좋습니다.

즉, 구조를 먼저 잡은 뒤 “이제 외부 서비스와 어떻게 연결하지?”가 궁금할 때 이 글을 보는 흐름이 가장 자연스럽습니다.

API를 가장 쉽게 설명하면 “주문 창구”다

식당에 갔다고 생각해보겠습니다.
손님은 주방 안으로 들어가 직접 요리하지 않습니다.
대신 주문 창구에서 “김치찌개 하나 주세요”라고 말합니다.
그러면 주방이 음식을 준비하고, 다시 결과를 내줍니다.

API도 비슷합니다.

내가 요청을 보낸다
상대 서비스가 그 요청을 처리한다
결과를 응답으로 준다

즉, API는 프로그램끼리 대화하는 통로입니다.

중요한 건 “직접 다 만든다”가 아니라,
이미 있는 기능을 정해진 방식으로 불러와 쓴다는 감각입니다.

웹서비스에서 API는 어디에 쓰일까

초보자가 체감하기 쉬운 예시는 아주 많습니다.

날씨 정보 가져오기
지도 표시하기
이메일 보내기
문자 발송하기
결제 요청하기
AI 답변 받기
번역이나 요약 결과 받기
광고 수익형 미니 도구에서 계산 결과 만들기

예를 들어 날씨 앱을 만든다고 해보겠습니다.
내가 직접 기상 관측소를 만드는 게 아니라, 날씨 API에 “서울 날씨를 알려줘”라고 요청하는 것입니다.
결과로 현재 온도, 하늘 상태, 강수 확률 같은 데이터를 받아서 화면에 보여주면 됩니다.

즉, API를 이해하는 순간부터는
“모든 기능을 다 직접 만들어야 한다”는 부담이 줄어듭니다.

핵심 구조는 “요청 – 처리 – 응답” 세 칸이면 충분하다

초보자가 API를 어려워하는 이유는 용어가 많아서입니다.
하지만 처음에는 아래 세 칸만 잡아도 됩니다.

1. 요청

내가 상대 서비스에 “이 일을 해달라”고 보내는 정보입니다.
예를 들면 도시 이름, 번역할 문장, 결제 금액, 검색어 등이 여기에 들어갑니다.

2. 처리

상대 서비스가 그 정보를 받아 내부에서 계산하거나 조회합니다.
이 부분은 보통 외부 서비스가 담당합니다.

3. 응답

처리 결과를 다시 돌려줍니다.
성공일 수도 있고, 실패 메시지일 수도 있고, 데이터 묶음일 수도 있습니다.

이 구조를 이해하면 “API 호출”이라는 말도 사실은
“외부 서비스에 부탁하고 답을 받는 일”로 바뀝니다.

GET과 POST는 왜 자꾸 나올까

초보자가 자주 보는 단어 중 하나가 GET과 POST입니다.
여기도 겁먹을 필요는 없습니다.

아주 단순하게 보면 이렇게 이해하면 됩니다.

GET

무언가를 가져올 때 많이 씁니다.
예: 오늘 환율 가져오기, 서울 날씨 가져오기, 내 게시글 목록 가져오기

POST

무언가를 보내서 저장하거나 처리 요청할 때 많이 씁니다.
예: 댓글 저장하기, 예약 등록하기, 결제 요청 보내기, 번역할 문장 보내기

물론 실제로는 더 다양한 방식이 있지만, 초보자의 첫 감각은 이 정도면 충분합니다.

즉,

GET = 가져오기
POST = 보내서 처리하기

정도로 이해해도 API를 보는 눈이 훨씬 편해집니다.

초보자가 진짜 조심해야 할 것은 “API 키”다

API를 붙이다 보면 거의 반드시 “키” 이야기가 나옵니다.
이 키는 쉽게 말해 내가 이 서비스를 사용할 권한이 있다는 증표입니다.

문제는 여기서 초보자가 자주 하는 실수가 있다는 점입니다.
작동만 되면 된다는 마음으로 API 키를 화면 코드에 그냥 넣어버리는 것입니다.

이건 매우 위험할 수 있습니다.
브라우저에서 그대로 보이거나, 다른 사람이 그 키를 써서 비용을 발생시키는 문제로 이어질 수 있기 때문입니다.

그래서 초보자는 최소한 이 감각은 꼭 가져가야 합니다.

공개되어도 되는 값이 있다
공개되면 안 되는 비밀 키가 있다
민감한 키는 프론트엔드에 직접 넣지 않는 편이 안전하다

즉, API 연결은 “붙이기”만이 아니라 어디서 처리하느냐도 중요합니다.

API 연결에서 초보자가 자주 막히는 5가지 이유

1. 문서를 안 보고 막연히 붙인다

요청 형식, 필요한 값, 응답 예시를 모르고 시작하면 금방 꼬입니다.
최소한 어떤 값을 보내야 하고 어떤 값을 받는지는 봐야 합니다.

2. 성공 케이스만 생각한다

초보자는 “잘 되면 어떤 결과가 오나”만 생각하고, 실패 응답은 놓치기 쉽습니다.
하지만 실제 연결에서는 실패 메시지가 훨씬 중요할 때가 많습니다.

3. 결과를 화면에만 띄우고 저장 흐름은 안 본다

예를 들어 AI 요약 결과를 받았는데, 그 결과를 저장하거나 기록으로 남기는 구조가 없으면 서비스가 반복 사용되기 어렵습니다.

4. API 비용 구조를 안 본다

호출할 때마다 비용이 드는 서비스는 사용량이 늘면 생각보다 부담이 커질 수 있습니다.
특히 수익화용 미니 툴에서는 이 부분을 먼저 계산해야 합니다.

5. 에러 메시지를 읽지 않고 다시 시킨다

“안 되는데 다시 연결해줘”라고 말하면 AI도 전체를 흔들 수 있습니다.
어떤 요청을 보냈고, 어떤 응답이나 오류가 왔는지를 같이 봐야 합니다.

API 비용은 “호출 수 x 사용량”으로 먼저 잡는다

API 연결에서 고급 기능처럼 보이는 것들은 대부분 비용 구조가 있습니다. 날씨나 지도처럼 조회 횟수로 계산되는 API도 있고, AI API처럼 입력과 출력 토큰에 따라 비용이 달라지는 API도 있습니다. 결제 API처럼 성공한 거래와 수수료가 중요한 경우도 있습니다.

초보자는 처음부터 복잡한 계산식을 만들 필요는 없습니다. 아래 네 가지 질문만 적어도 충분합니다.

질문	왜 중요한가
사용자 행동 1번에 API를 몇 번 호출하는가	버튼 한 번에 API 1회인지, 내부에서 3~5회인지에 따라 비용이 달라집니다
응답을 저장해서 재사용할 수 있는가	매번 새로 호출하지 않으면 비용과 속도를 줄일 수 있습니다
실패한 요청도 비용이나 제한에 영향을 주는가	오류 재시도가 많으면 사용량이 빨리 늘 수 있습니다
무료 사용자가 늘어도 감당 가능한가	광고 수익보다 API 비용이 빨리 늘면 서비스가 손해가 됩니다

특히 AI 기능을 붙일 때는 “답변이 잘 나오나”만 보지 말고, 질문 한 번에 들어가는 입력 토큰과 출력 토큰을 같이 봐야 합니다. 자세한 원가 감각은 토큰은 공짜가 아니다에서 이어서 보면 좋습니다.

API 키는 프론트엔드가 아니라 서버에서 다룬다

비개발자가 바이브코딩으로 API를 붙일 때 가장 위험한 실수는 비밀 키를 화면 코드에 넣는 것입니다. 브라우저에 내려가는 코드는 사용자가 볼 수 있다고 생각해야 합니다.

기본 기준은 아래처럼 잡으면 됩니다.

공개되어도 되는 설정값은 프론트엔드에 둘 수 있다
결제, AI, 문자, 메일 발송처럼 비용이 발생하는 비밀 키는 서버에서 처리한다
.env 파일이나 서버 환경변수에 키를 보관한다
GitHub 같은 공개 저장소에 비밀 키를 올리지 않는다
키가 노출됐다고 의심되면 즉시 폐기하고 새 키를 만든다

이 기준을 모르면 API 연결은 처음에는 잘 되는 것처럼 보여도 나중에 비용 사고로 이어질 수 있습니다. 그래서 API 연결은 기능 구현이 아니라 권한과 비용을 함께 관리하는 일로 보는 편이 안전합니다.

AI에게는 이렇게 물어야 덜 꼬인다

API 연결은 막연한 질문이 특히 위험합니다.
아래처럼 구조를 나눠서 물으면 훨씬 좋습니다.

예시 1:

이 API는 도시 이름을 보내면 날씨 정보를 JSON으로 돌려준다.
초보자 기준으로 요청값, 응답값, 화면 표시 흐름을 먼저 설명해줘.

예시 2:

POST 요청으로 예약 정보를 보내고 있는데 저장이 안 된다.
보내는 값 형식 문제인지, 인증 문제인지, 서버 응답 문제인지 순서대로 점검해줘.

예시 3:

이 기능은 브라우저에서 바로 호출하면 안 되는 비밀 키가 필요하다.
프론트엔드와 서버 역할을 어떻게 나눠야 하는지 설명해줘.

이렇게 말하면 AI도 “다시 짜기”보다
문제의 층위를 분리해서 설명하는 방향으로 움직입니다.

결국 API를 이해한다는 것은 “외부 기능을 빌려오는 감각”을 익히는 일이다

초보자가 API를 배우는 이유는 개발자가 되기 위해서가 아닙니다.
오히려 반대입니다.

혼자 다 만들지 않아도 필요한 기능을 연결할 수 있다는 감각을 익히기 위해서입니다.

이 감각이 생기면, 바이브코딩으로 만들 수 있는 서비스 범위가 갑자기 넓어집니다.

날씨 정보 툴
번역 도구
문장 생성기
메일 발송 서비스
결제형 미니 SaaS

이 모든 것이 “외부 기능을 어떻게 붙이느냐”의 문제로 바뀝니다.

같이 보면 좋은 공식 문서

그리고 여기서부터는 또 다른 질문이 생깁니다.
“기능을 계속 붙이다 보면 왜 프로젝트가 점점 꼬이지?”
그 질문에 답하는 다음 파트가 바로 11편, 구조와 스파게티 코드 이야기입니다.

바이브코딩 전체 순서 보기

바이브코딩 뜻, 하는법, 도구 선택, API 연결, 데이터베이스, 배포 흐름은 바이브코딩 가이드에서 이어서 볼 수 있습니다.