9장: API 활용하기 — 외부 서비스 연결
API가 뭔가
8장에서 Supabase로 데이터를 저장하고 불러오는 기능을 만들었습니다. 그런데 서비스를 만들다 보면 직접 만들 수 없는 기능이 필요해집니다. 날씨 정보, 결제 처리, AI 텍스트 생성, 지도 표시, 이메일 발송. 이런 기능을 처음부터 만들려면 몇 달이 걸립니다. 하지만 이미 만들어둔 회사들이 있고, 그 기능을 가져다 쓸 수 있습니다.
이때 쓰는 것이 API입니다.
API(Application Programming Interface)는 프로그램끼리 대화하는 방법입니다. 비유하자면 음식점의 주문 창구입니다. 주방에서 어떻게 요리하는지 몰라도, 창구에서 "비빔밥 하나요"라고 말하면 비빔밥이 나옵니다. 주방의 레시피, 재료, 조리 도구를 알 필요 없습니다. 메뉴에 있는 것만 주문하면 됩니다.
API도 같습니다. 날씨 API에 "서울 날씨 알려줘"라고 요청하면 기온, 습도, 날씨 상태가 담긴 데이터가 돌아옵니다. 날씨 데이터를 어디서 수집하고 어떻게 분석하는지 몰라도 됩니다.
요청과 응답
API의 동작 방식은 단순합니다. 요청(request)을 보내면 응답(response)이 돌아옵니다.
요청은 보통 이런 형태입니다.
GET https://api.weather.com/current?city=seoul
GET은 "데이터를 달라"는 뜻이고, 뒤에 오는 주소가 어디에 요청할지를 나타냅니다. ?city=seoul은 "서울 날씨를 달라"는 조건입니다.
응답은 이런 형태로 돌아옵니다.
{
"city": "Seoul",
"temperature": 22,
"condition": "맑음"
}
이 형식을 JSON이라고 합니다. 사람이 읽을 수도 있고 프로그램이 처리할 수도 있는 데이터 형식입니다. { } 안에 이름과 값이 쌍으로 들어갑니다.
요청 방식은 크게 두 가지입니다.
GET — 데이터를 가져올 때 씁니다. 날씨 조회, 뉴스 목록 조회 등.
POST — 데이터를 보낼 때 씁니다. 결제 요청, 이메일 발송, AI에게 질문 보내기 등.
이 두 가지만 알면 대부분의 API를 쓸 수 있습니다. 직접 GET이나 POST를 입력할 일은 없습니다. Claude Code에게 "이 API를 연결해줘"라고 말하면 알아서 코드를 작성합니다.
API 키 — 누가 쓰는지 확인하는 열쇠
대부분의 API는 아무나 쓸 수 없습니다. 회원가입을 하고 API 키를 발급받아야 합니다. API 키는 "이 요청은 이 사람이 보냈다"는 것을 증명하는 고유한 문자열입니다.
sk-abc123def456ghi789...
이런 긴 문자열을 API를 호출할 때마다 함께 보냅니다. API 제공자는 이 키를 보고 누가 얼마나 사용했는지 추적하고, 요금을 부과합니다.
API 키를 다루는 규칙
첫째, .env 파일에 저장합니다. 코드 안에 직접 넣지 않습니다.
# .env
WEATHER_API_KEY=sk-abc123def456ghi789
둘째, GitHub에 올리지 않습니다. 7장에서 배운 .gitignore에 .env가 포함되어 있는지 다시 확인하세요. API 키가 GitHub에 올라가면 다른 사람이 여러분의 키로 API를 마음대로 쓸 수 있고, 여러분에게 요금을 청구합니다.
셋째, 프론트엔드 코드에 넣지 않습니다. 브라우저가 실행하는 코드에 API 키를 넣으면 누구나 개발자 도구로 볼 수 있습니다. API 호출은 서버 쪽 코드(Next.js의 API Route나 Server Action)에서 하고, 브라우저는 서버를 거쳐 결과만 받습니다.
이 규칙이 복잡해 보여도 걱정하지 마세요. Claude Code에게 "API 키를 안전하게 관리해줘"라고 말하면 서버 쪽에서 호출하고 환경변수로 관리하는 코드를 알아서 만듭니다.
API 문서 읽기
API를 쓰려면 그 API의 문서(documentation)를 봐야 합니다. 어떤 주소로 요청해야 하는지, 어떤 값을 보내야 하는지, 어떤 값이 돌아오는지 나와 있습니다. 음식점의 메뉴판과 같습니다. 메뉴판 없이 "아무거나 주세요"라고 하면 안 되듯이, API도 문서에 정의한 대로 요청해야 합니다.
하지만 API 문서는 개발자를 위해 작성한 것이라 처음 보면 어렵게 느낄 수 있습니다. 이때도 Claude Code가 도와줍니다.
[API 문서 URL]
이 API를 사용해서 [원하는 기능]을 만들어줘.
Claude Code가 문서를 읽고 필요한 코드를 작성합니다.
API 문서를 찾지 못하겠으면 먼저 물어볼 수도 있습니다.
날씨 정보를 무료로 가져올 수 있는 API를 추천해줘.
가입 방법과 API 키 발급 방법도 알려줘.
Claude Code로 외부 API 연결하기
실제로 API를 연결하는 과정을 보겠습니다.
예시 1: AI 기능 추가하기
프로젝트에 AI 텍스트 생성 기능을 넣고 싶다면 이렇게 합니다.
1단계: API 키를 발급받습니다. https://console.anthropic.com (새 탭에서 열림) 에서 Claude API 키를 만들 수 있습니다.
2단계: Claude Code에게 시킵니다.
Claude API를 사용해서 텍스트 요약 기능을 만들어줘.
API 키: [발급받은 키]
- 사용자가 긴 글을 입력하면 3줄로 요약해서 보여줘
- API 키는 .env에 저장하고 서버 쪽에서 호출해줘
Claude Code가 API Route를 만들고, 프론트엔드에서 그 Route를 호출하는 구조로 코드를 작성합니다.
예시 2: 이메일 발송
사용자에게 이메일을 보내는 기능을 추가하고 싶다면:
Resend API로 이메일 발송 기능을 만들어줘.
회원가입하면 환영 이메일을 보내는 기능이야.
API 키: [발급받은 키]
예시 3: 결제 연동
Toss Payments API로 결제 기능을 만들어줘.
테스트 모드로 먼저 구현해줘.
결제처럼 돈이 오가는 API는 대부분 테스트 모드를 제공합니다. 실제 돈이 나가지 않는 가상 환경에서 먼저 개발하고, 완성한 후에 실제 모드로 전환합니다.
자주 쓰는 API 유형
바이브코딩 프로젝트에서 자주 쓰는 API를 유형별로 정리합니다. 직접 찾아 가입하고 API 키를 발급받으면 됩니다.
| 유형 | 대표 서비스 | 용도 |
|---|---|---|
| AI/텍스트 | Claude API, OpenAI API | 텍스트 생성, 요약, 번역 |
| 이메일 | Resend, SendGrid | 이메일 발송 |
| 결제 | Toss Payments, Stripe | 결제 처리 |
| 지도 | Google Maps, Kakao Maps | 지도 표시, 주소 검색 |
| 파일 저장 | Supabase Storage, AWS S3 | 이미지, 파일 업로드 |
| 알림 | Slack API, Discord Webhook | 메시지 알림 |
| 인증 | Google OAuth, Kakao Login | 소셜 로그인 |
이 중에서 이미 쓰고 있는 것도 있습니다. 8장에서 연결한 Supabase도 API입니다. Supabase 클라이언트 라이브러리가 API 호출을 대신 해주고 있을 뿐, 내부적으로는 Supabase 서버에 요청을 보내고 응답을 받는 구조입니다.
API 연동이 안 될 때
API를 연결하다 보면 에러를 자주 만납니다. 대부분 몇 가지 패턴에 해당합니다.
401 Unauthorized
API 키가 잘못됐거나 빠졌을 때 나옵니다.
API 호출에서 401 에러가 나.
API 키가 제대로 설정됐는지 확인해줘.
.env 파일에 키가 있는지, 변수 이름이 코드에서 쓰는 이름과 일치하는지 확인합니다. .env 파일을 수정한 뒤에는 개발 서버를 다시 시작해야 합니다(Ctrl+C 후 npm run dev).
403 Forbidden
API 키는 맞지만 해당 기능을 쓸 권한이 없을 때 나옵니다. 무료 요금제에서 유료 기능을 호출하면 이 에러가 날 수 있습니다.
429 Too Many Requests
짧은 시간에 너무 많은 요청을 보냈을 때 나옵니다. 대부분의 API에는 분당 또는 일당 요청 횟수 제한이 있습니다. 잠시 기다렸다가 다시 시도하면 됩니다.
500 Internal Server Error
API 제공자 쪽 서버에 문제가 생긴 것입니다. 내 코드의 문제가 아닙니다. 시간을 두고 다시 시도합니다.
에러 코드를 외울 필요 없습니다. 브라우저 개발자 도구 Network 탭에서 빨간 요청을 클릭하면 상태 코드와 에러 메시지가 보입니다. 그대로 Claude Code에게 붙여넣으면 됩니다.
API 호출하면 이런 에러가 나.
[Network 탭 에러 내용 붙여넣기]
고쳐줘.
서버 vs 클라이언트 — API는 어디서 호출하나
API를 연결할 때 가장 중요한 판단이 하나 있습니다. 이 API를 브라우저에서 직접 호출할지, 서버를 거쳐서 호출할지입니다.
브라우저에서 직접 호출해도 되는 경우:
- API 키가 필요 없는 공개 API
- Supabase처럼 Publishable key를 쓰는 서비스 (RLS 적용)
서버를 거쳐야 하는 경우:
- Secret key가 필요한 API (Claude API, 결제 API 등)
- 요청 내용을 사용자가 볼 수 없어야 하는 경우
Next.js에서는 서버 쪽 코드를 쉽게 만들 수 있습니다. API Route(app/api/ 폴더)나 Server Action을 쓰면 됩니다. Claude Code에게 "서버 쪽에서 호출해줘"라고 말하면 적절한 방식으로 코드를 만듭니다.
이 구분이 어려워 보여도 괜찮습니다. Claude Code에게 API 연동을 시키면 대부분 알아서 올바른 위치에 코드를 만듭니다. 다만 한 가지는 기억하세요. Secret이 들어간 API 키는 절대 브라우저 코드에 넣으면 안 됩니다.
✏️ 실습: 외부 API를 하나 연결해보기
8장에서 만든 프로젝트에 외부 API를 연결합니다. 아래 중 하나를 골라서 해봅니다.
선택지 A — AI 텍스트 기능:
Claude API를 연결해서, 사용자가 입력한 글을 3줄로 요약하는 기능을 만들어줘.
API 키는 .env에 저장하고, 서버 쪽에서 호출해줘.
선택지 B — 이메일 알림:
Resend API를 연결해서, 버튼을 누르면 내 이메일로 테스트 메일을 보내는 기능을 만들어줘.
선택지 C — 자기 프로젝트에 필요한 API:
프로젝트에 필요한 외부 서비스가 있다면 직접 연결해봅니다.
[API 이름]을 연결해줘.
[원하는 기능]을 만들어줘.
API 키: [발급받은 키]
확인할 것:
- 기능이 동작하는지 브라우저에서 확인합니다
.env에 API 키를 저장했는지 확인합니다.gitignore에.env가 들어 있는지 확인합니다- 동작하면 커밋합니다
API 연동을 완료했어. 커밋하고 GitHub에 올려줘.
다음 장에서는 개발 중에 만나는 에러에 대처하는 방법을 다룹니다.
참고자료