# API란 무엇인가

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

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

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

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

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

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

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

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

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

## REST와 JSON

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

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

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

읽는 법은 [데이터의 형태](/guide/it-data-formats)에서 이어집니다.

## 열쇠 — API 키

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

```
Authorization: Bearer sk_live_a1b2c3…
```

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

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

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

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

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

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

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

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

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

## 부를 때 지켜야 하는 것

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

## 자주 하는 오해

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

**아닙니다.** 키를 가진 쪽만 부를 수 있습니다. 다만 **키가 곧 문**이라, 키
관리가 곧 보안입니다 — [계정 · 비밀번호 · API 키 · 권한](/guide/it-accounts).

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

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

---

## 확인

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

<details>
<summary>답</summary>

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

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

<details>
<summary>답</summary>

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

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

<details>
<summary>답</summary>

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

---

여기까지를 직접 눈으로 봅니다 →
[요청 하나를 직접 뜯어보기](/guide/it-try-http)