REST API

🤔 혹시 이런 경험 있나요?

AI에게 "날씨 앱 만들어줘"라고 했더니 코드에 fetch('https://api.weather.com/...')이 보입니다. 또는 OpenAI를 사용하려면 "API 키를 발급받으세요"라는 안내가 나옵니다. API라는 단어는 바이브코딩을 하면 거의 매번 마주치는데, 도대체 이게 뭘까요?

🍽️ 레스토랑으로 이해하는 API

레스토랑에서 식사를 주문하는 상황을 생각해보세요.

• 손님(여러분의 앱): 까르보나라를 먹고 싶습니다.
• 웨이터(API): 손님의 주문을 받아 주방에 전달합니다.
• 주방(서버): 실제로 음식을 만들어서 웨이터에게 건네줍니다.
• 메뉴판(API 문서): 주문할 수 있는 것들과 방법이 적혀 있습니다.

손님은 주방에 직접 들어갈 수 없습니다. 대신 웨이터(API)에게 정해진 방식으로 요청하면, 원하는 결과를 받을 수 있습니다. API도 마찬가지입니다. 여러분의 프로그램이 다른 서비스에 직접 접근할 수 없지만, 정해진 규칙(API)을 통해 데이터를 요청하고 응답받을 수 있습니다.

📬 HTTP 메서드: 요청의 종류

API에 요청을 보낼 때는 "무엇을 하고 싶은지"를 함께 알려야 합니다. 이것을 HTTP 메서드라고 합니다.

바이브코딩에서 AI가 생성한 코드를 보면 이런 구조를 자주 만나게 됩니다.

// GET: 사용자 목록 가져오기
fetch('https://api.example.com/users')

// POST: 새 게시글 작성하기
fetch('https://api.example.com/posts', {
  method: 'POST',
  body: JSON.stringify({ title: '제목', content: '내용' })
})

📦 JSON: API가 사용하는 언어

API끼리 데이터를 주고받을 때는 대부분 JSON(JavaScript Object Notation) 형식을 사용합니다. 사람도 읽을 수 있고, 컴퓨터도 이해할 수 있는 텍스트 형태입니다.

{
  "name": "홍길동",
  "email": "hong@example.com",
  "age": 28
}

중괄호 {} 안에 "키": "값" 형태로 데이터가 들어 있습니다. AI에게 "유저 정보를 JSON으로 보내줘"라고 하면, 이런 형태의 데이터를 만들어줍니다.

🔑 API 키: 왜 항상 필요할까요?

바이브코딩을 하다 보면 OpenAI, Google Maps, Supabase 등 외부 서비스를 사용할 때마다 API 키를 요구받습니다. API 키는 레스토랑의 예약 번호와 같습니다.

• 누가 요청했는지 확인합니다 (인증)
• 얼마나 사용했는지 추적합니다 (사용량 관리)
• 남용을 방지합니다 (보안)

API 키 없이 요청하면 서버는 "당신이 누군지 모르겠으니 거부합니다"라고 응답합니다. 그래서 AI가 만들어준 코드에 OPENAI_API_KEY 같은 환경 변수가 항상 등장하는 것입니다.

⚠️ 바이브코딩할 때 흔한 API 실수

1. API 키를 코드에 직접 넣는 실수

// 절대 이렇게 하면 안 됩니다
const apiKey = 'sk-abc123...'

// 환경 변수를 사용하세요
const apiKey = process.env.OPENAI_API_KEY

API 키를 코드에 그대로 적으면 GitHub에 올렸을 때 전 세계에 공개됩니다. 반드시 환경 변수(.env 파일)에 보관해야 합니다.

2. 에러 응답을 무시하는 실수

API는 항상 상태 코드를 함께 보내줍니다.

• 200: 성공입니다.
• 401: 인증 실패입니다. API 키가 잘못되었을 수 있습니다.
• 404: 요청한 데이터가 없습니다.
• 429: 요청을 너무 많이 보냈습니다 (속도 제한).
• 500: 서버 쪽 문제입니다.

AI가 만든 코드에서 에러가 나면, 먼저 이 상태 코드를 확인해보세요. 대부분의 문제 원인을 파악할 수 있습니다.

3. REST API의 URL 구조를 모르는 실수

REST API는 URL 자체가 데이터의 위치를 나타냅니다.

GET  /users          → 전체 사용자 목록
GET  /users/123      → 123번 사용자 정보
POST /users          → 새 사용자 생성
GET  /users/123/posts → 123번 사용자의 게시글 목록

URL만 봐도 "어떤 데이터에 접근하는지"를 알 수 있도록 설계하는 것이 REST API의 핵심 원칙입니다.

📋 30초 요약

1. API는 프로그램 간의 약속된 소통 방식입니다. 레스토랑의 웨이터처럼, 정해진 규칙으로 요청하면 원하는 데이터를 받을 수 있습니다.

2. HTTP 메서드(GET/POST/PUT/DELETE)로 요청의 종류를 구분하고, 데이터는 JSON 형식으로 주고받습니다.

3. API 키는 코드가 아닌 환경 변수에 보관해야 합니다. 에러가 발생하면 상태 코드(200, 401, 404, 500 등)를 먼저 확인하는 습관을 들이세요.