API란 무엇인가

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

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

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

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

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

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

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

REST와 JSON

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

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

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

열쇠 — API 키

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

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

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

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

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

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

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

부를 때 지켜야 하는 것

자주 하는 오해

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

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

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

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

---

확인

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

답

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

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

답

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

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

답

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

---

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