API란 — 식당 메뉴판으로 이해하기

이 토픽을 마치면

API가 뭔지 한 문장으로 설명할 수 있고, Method / Endpoint / Parameter가 뭔지 알게 됩니다.

개발자끼리 대화하다 보면

"이거 API 연동하면 돼" "그 API 키 발급받았어?" "REST API로 해"

이 단어가 하루에도 수십 번 나옵니다. 근데 막상 API가 뭐냐고 물으면 "어... 데이터 주고받는 거?" 하고 얼버무리는 경우가 많습니다. 한번 제대로 정리해봅시다.

식당에 갔다고 생각해보세요

식당에 가면 주방에 직접 들어가서 냉장고 열고 고기 꺼내고 불 켜고 굽고... 이러지 않습니다. 메뉴판을 보고 "1번 삼겹살 주세요" 하면 됩니다.

API도 이거랑 똑같습니다.

서버(주방)에 직접 접근하지 않고, 서버가 미리 정해놓은 메뉴(API 문서)를 보고 정해진 방식으로 요청합니다. 서버는 메뉴에 있는 것만 해줍니다. 메뉴에 없는 건 아무리 부탁해도 안 됩니다.

API = 프로그램끼리 데이터를 주고받기 위해 서버가 정해놓은 약속

여기서 중요한 건 "정해놓은"입니다. 서버가 정한 규칙대로만 요청해야 응답이 옵니다.

API 요청의 3요소

식당에서 주문할 때도 세 가지를 말합니다:

뭘 할 건지 — "주문할게요" / "취소할게요"
어디에 — "1번 테이블이요"
추가 정보 — "곱빼기요, 반숙으로요"

API 요청도 똑같이 세 조각입니다:

text

GET https://api.weather.com/today?city=seoul
│    │                              │
Method  Endpoint                   Parameter
(뭘)   (어디에)                    (추가 정보)

하나씩 봅시다.

Method — 뭘 할 건지를 동사로 말하는 겁니다.

Method	의미	식당 비유
`GET`	데이터 가져오기	"메뉴 좀 보여주세요"
`POST`	새 데이터 보내기	"이거 주문할게요"
`PUT`	데이터 수정하기	"아까 주문 변경이요"
`DELETE`	데이터 삭제하기	"주문 취소요"

Endpoint — 서버의 어느 주소로 보낼 건지. URL입니다.

Parameter — 추가 조건. ?city=seoul처럼 물음표 뒤에 붙이거나, POST일 때는 본문(body)에 담아 보냅니다.

이 세 개만 알면 세상의 모든 API를 쓸 수 있습니다. 진짜입니다.

실제로 써보기

브라우저 주소창에 이걸 그대로 입력해보세요:

text

https://jsonplaceholder.typicode.com/users/1

뭔가 JSON 데이터가 쫙 나올 겁니다. 가짜 유저 1번의 정보입니다. 방금 API를 호출한 겁니다. 별거 아니죠?

JavaScript로 하면 이렇습니다:

javascript

// 유저 1번 정보를 가져오는 API 호출
const res = await fetch('https://jsonplaceholder.typicode.com/users/1');
const user = await res.json();
console.log(user.name);  // "Leanne Graham"

fetch에 URL(Endpoint)을 넣고, 응답을 JSON으로 변환하고, 원하는 데이터를 꺼냅니다. 이 세 줄이 API 호출의 전부입니다.

fetch는 기본이 GET이라서 Method를 따로 안 적었습니다. POST로 데이터를 보내고 싶으면:

javascript

// 새 게시물을 등록하는 API 호출
await fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: '첫 글', body: '안녕하세요' })
});

method를 POST로 바꾸고, body에 보낼 데이터를 담으면 됩니다.

Public vs Private — 누구한테 열어줄 건지

모든 API가 아무나 쓸 수 있는 건 아닙니다.

Public API — 아무나 쓸 수 있음. 위에서 해본 jsonplaceholder가 이겁니다.
Private API — 회사 내부에서만. 밖에 안 열어줍니다.
Partner API — 계약한 회사끼리만 공유.

네이버 파파고 번역 API, 카카오 지도 API — 이런 건 Public이지만 API 키를 발급받아야 쓸 수 있습니다. 키 없이 막 쓰면 차단당합니다.

왜 키를 요구할까요? 공짜로 무제한 쓰게 해주면 서버가 터지니까요. 그래서 "하루 1000번까지 무료, 그 이상은 돈 내세요" 같은 유료 모델이 많습니다. 파파고, 클로바, 구글 번역 전부 이런 식입니다.

핵심

API는 서버가 정해놓은 메뉴판입니다. 메뉴판에 없는 건 주문할 수 없고, 메뉴판에 적힌 방식대로만 요청해야 합니다. Method(뭘 할 건지) + Endpoint(어디로) + Parameter(추가 조건) — 이 세 개면 끝입니다.