API란 무엇인가

이 장에서 배우는 것 API가 정확히 무엇인지, 엔드포인트 · 키 · SDK 같은 말이 각각 어디를 가리키는지, 그리고 화면이 있는데도 API를 쓰는 이유.

사람용 창구와 프로그램용 창구

같은 은행이라도 창구가 둘입니다. 사람이 줄 서는 창구와, 다른 은행 전산이 붙는 전용 회선. API는 뒤쪽입니다.

	화면(UI)	API
쓰는 쪽	사람	다른 프로그램
모양	버튼과 표	주소와 JSON
잘하는 것	눈으로 보고 판단	반복 · 대량 · 자동

API(Application Programming Interface) — 직역하면 "프로그램이 쓰라고 만든 접점"입니다. 그 이상의 뜻은 없습니다.

엔드포인트 — 창구 하나하나

API는 보통 여러 개의 주소로 이루어집니다. 그 주소 하나를 엔드포인트라고 합니다. REST로 업무 시키기의 목록을 예로 보면 이렇습니다.

하는 일	메서드 + 엔드포인트
업무 목록 보기	`GET /api/v1/tasks`
업무 만들기	`POST /api/v1/tasks`
업무 하나 보기	`GET /api/v1/tasks/{id}`
중지	`POST /api/v1/tasks/{id}/stop`

메서드와 주소의 조합이 곧 기능입니다. 같은 /tasks 라도 GET 이면 조회, POST 면 생성입니다. {id} 는 "여기에 실제 번호가 들어간다"는 표기입니다.

REST와 JSON

오늘 쓰는 API의 대부분은 이 두 단어로 설명됩니다.

REST — "주소는 사물, 메서드는 동작"으로 짜자는 관행. 위 표가 그 모양입니다.
JSON — 주고받는 내용의 표기법. 사람도 읽을 수 있는 텍스트입니다.

json

{  "id": "task_9f2",  "status": "running",  "prompt": "지난주 반품 데이터를 정리해줘"}

읽는 법은 데이터의 형태에서 이어집니다.

열쇠 — API 키

화면에는 로그인이 있습니다. API에는 키가 있습니다.

text

Authorization: Bearer sk_live_a1b2c3…

	비밀번호	API 키
쓰는 쪽	사람	프로그램
개수	하나	용도마다 여러 개
잃어버리면	재설정	그 키만 폐기

용도마다 따로 발급하는 것이 핵심입니다. 하나가 새면 그 하나만 지우면 되기 때문입니다. API 키로 외부에서 부르기가 이름을 제대로 지으라고 강조하는 이유도 이것입니다 — 이름이 없으면 어느 것을 지워야 할지 모르게 됩니다.

SDK — 남이 미리 싸둔 도구 상자

API를 직접 부르려면 주소를 만들고 헤더를 붙이고 응답을 해석해야 합니다. 그 과정을 언어별로 미리 감싸둔 것이 SDK(라이브러리)입니다.

text

직접 부르기   주소를 만들고 → 헤더를 붙이고 → 응답을 JSON으로 풀고SDK          client.tasks.create("…")

하는 일은 같습니다. 그래서 내 컴퓨터를 모델 서버로가 "OpenAI SDK의 base 주소만 바꾸면 된다"고 말할 수 있는 것입니다 — 창구의 모양이 같으면 도구 상자를 그대로 씁니다.

화면이 있는데도 API를 쓰는 이유

text

□ 같은 일을 매일 반복한다        → 사람이 누르는 대신 예약이 부릅니다□ 다른 시스템에 결과가 필요하다   → 사내 포털·Slack 봇이 직접 가져갑니다□ 건수가 많다                   → 300건을 사람이 누르지 않습니다□ 기록이 남아야 한다             → 누가 무엇을 불렀는지 로그에 남습니다

한 건을 눈으로 보고 판단하는 일이면 화면이 낫습니다. API는 그 반대편의 도구입니다.

부를 때 지켜야 하는 것

개념	뜻	마주치는 순간
레이트 리밋	정해진 시간에 몇 번까지	`429` 응답
타임아웃	몇 초까지 기다릴지	오래 걸리는 작업
재시도	실패 시 다시 부르기	`POST` 는 중복 생성 주의
버전	`/api/v1` 의 `v1`	규격이 바뀌어도 옛것이 남음

자주 하는 오해

"API를 열면 우리 데이터가 공개되나요"

아닙니다. 키를 가진 쪽만 부를 수 있습니다. 다만 키가 곧 문이라, 키 관리가 곧 보안입니다 — 계정 · 비밀번호 · API 키 · 권한.

"API가 있으면 개발자가 있어야 하나요"

부르는 쪽에 프로그램이 필요하다는 뜻은 맞습니다. 다만 요즘은 그 프로그램을 에이전트에게 짜게 하는 경우가 많고, MCP는 아예 그 연결을 표준화한 것입니다.

확인

1. 엔드포인트와 메서드의 관계는?

답

조합이 곧 기능입니다. 같은 /tasks 주소라도 GET 이면 조회, POST 면 생성입니다.

2. API 키를 용도마다 따로 발급하는 이유는?

답

하나가 새면 그것만 폐기할 수 있기 때문입니다. 그래서 어느 키가 무엇에 쓰이는지 알아볼 이름이 필요합니다.

3. SDK는 API와 다른 것입니까?

답

같은 API를 부르는 도구 상자입니다. 주소·헤더·응답 해석을 언어별로 미리 감싸둔 것이라 하는 일은 같습니다.

여기까지를 직접 눈으로 봅니다 → 요청 하나를 직접 뜯어보기