01. API란 무엇인가?

API(Application Programming Interface)는 직역하면 '애플리케이션(Application)끼리 대화하기 위한 약속(Interface)'입니다. 사람과 사람이 언어로 대화하듯, 소프트웨어끼리는 API를 통해 서로 데이터를 주고받습니다.

"복잡한 내부 사정은 숨기고(Hiding), 약속된 서비스만 내어주는(Exposing) 기술적 계약"

0. API의 짧은 역사: "자유로움에서 규격으로"

API는 갑자기 하늘에서 떨어진 개념이 아니라, 더 쉽고 가볍게 소통하기 위해 진화해왔습니다.

1990년대 (RPC, Remote Procedure Call - 원격 호출): "다른 컴퓨터에 있는 기능을 내 것처럼 쓰자!"라는 아이디어에서 시작했지만, 연결 방법이 너무 복잡했습니다.
2000년대 초반 (SOAP, Simple Object Access Protocol - 엄격한 규격): 모든 대화를 아주 복잡하고 무거운 XML 서류 봉투에 담아 주고받았습니다. 규칙이 너무 까다로워 배우기가 힘들었습니다.
2010년대~현재 (REST & JSON - 가볍고 직관적인 대화): "그냥 웹 주소(URL)를 쓰고, 누구나 읽기 쉬운 텍스트(JSON, JavaScript Object Notation)로 주고받자!"라는 REST(Representational State Transfer) 방식이 등장하며 API의 폭발적인 대중화가 시작되었습니다.
2026년~미래 (AI Agent & Agentic Workflow - 자율적 행동): 이제 API는 사람이 코딩하는 도구를 넘어, AI가 스스로 판단하고 세상을 조작하는 'AI의 손과 발'로 진화하고 있습니다.

1. The Analogy: 왜 우리는 주방에 들어가지 못할까?

여러분이 식당에 가서 스테이크를 주문한다고 상상해봅시다. 배가 고프다고 해서 직접 주방에 들어가 냉장고를 뒤지고 고기를 굽지는 않습니다. 왜 그럴까요?

안전과 보안 (Security): 주방에는 뜨거운 불과 날카로운 칼이 있습니다. 손님이 다치거나, 실수로 식재료를 오염시키면 안 됩니다.
효율과 추상화 (Abstraction): 여러분은 스테이크 굽는 법을 몰라도 됩니다. 그냥 "미디엄으로 구워주세요"라는 요청만 할 줄 알면 결과를 얻습니다.
손님 (Client): 데이터를 요청하는 쪽 (웹 브라우저, 스마트폰 앱, 나의 파이썬 코드)
주방 (Server): 복잡한 로직과 소중한 데이터가 담긴 곳 (데이터베이스, 연산 알고리즘)
점원/메뉴판 (API): 손님의 주문을 받아 주방에 전달하고, 결과물을 가져다주는 유일한 통로.

API의 핵심 가치

손님(Client)이 주방(Server)의 내부 코드를 몰라도, "메뉴판(API Document)에 적힌 대로 요청하면 데이터가 나온다"는 신뢰를 제공하는 것입니다.

2. Visible Thinking: 소통의 흐름 (Request & Response)

소프트웨어 사이의 대화는 "요청(Request)"과 "응답(Response)"이라는 핑퐁 게임입니다.

sequenceDiagram
    participant Client as 🙋 손님 (Client / Python Code)
    participant API as 🤵 점원 (API / Interface)
    participant Kitchen as 👨🍳 주방 (Server / DB)

    Note over Client, API: 1. Request (요청)
    Client->>API: "3번 테이블, 스테이크 하나 주세요."

    Note over API, Kitchen: 2. Processing (처리)
    API->>Kitchen: "3번 주문 들어왔어! 고기 구워!"
    Kitchen->>Kitchen: (데이터 조회 및 가공 중...)
    Kitchen-->>API: 요리 완성 (Data)

    Note over Client, API: 3. Response (응답)
    API-->>Client: "주문하신 스테이크(JSON 데이터) 나왔습니다."

🥩 스테이크(데이터)는 어떻게 생겼을까요?

우리가 API를 통해 받는 결과물(스테이크)은 실제로 아래와 같은 JSON 형태입니다.

{
  "menu": "T-Bone Steak",
  "doneness": "Medium",
  "sauce": "Red Wine",
  "price": 55000
}

3. Interface: 엄격한 '메뉴판'의 약속

API의 I는 Interface(접점/경계면)입니다. 이 메뉴판은 기계가 알아들어야 하기에 아주 엄격한 규칙을 따릅니다.

규칙: 메뉴판에 "스테이크"라고 적혀 있는데 "고기 덩어리"라고 부르면 점원은 알아듣지 못합니다. (Error 발생)
효과: 이 규칙(Spec)만 지키면 주방장이 바뀌든 주방 구조가 바뀌든, 손님은 항상 같은 결과를 얻을 수 있습니다.

4. API의 종류 (Business Perspective)

사업적 관점에서 API는 '누구에게 이 메뉴판을 보여줄 것인가'에 따라 가치가 달라집니다.

종류	비유	비즈니스 의미	예시
Public API	길거리 푸드트럭	누구나 우리 기술을 쓰게 하여 생태계를 확장함	Google Maps, 공공 데이터, ChatGPT API
Partner API	전용 멤버십 식당	특정 비즈니스 파트너와만 기술을 공유하여 협업함	배달의민족-식당 포스기 연동
Private API	집밥/사내 식당	외부 노출 없이 우리 서비스 내부의 효율을 높임	배달의민족 앱 - 배달의민족 서버 간의 통신

5. Modern Standard: RESTful API (주소 짓는 약속)

과거에는 개발자마다 API 이름을 짓는 방식이 제멋대로였습니다. (/get_user, /deleteItem, /update-info 등) 마치 메뉴판 이름이 식당마다 외계어처럼 적혀 있는 꼴이었죠. 이를 해결하기 위해 전 세계 개발자들이 만든 표준 약속이 바로 REST(Representational State Transfer) 입니다.

5-1. 핵심 원칙: 명사와 동사의 분리

RESTful API는 딱 두 가지만 기억하면 됩니다.

주소(URL)에는 오직 '명사(대상)'만 쓴다. (무엇을?)
행동은 'HTTP Method(동사)'로 표현한다. (어떻게?)

5-2. RESTful 방식의 직관성 (비교)

목표	옛날 방식 (Bad)	RESTful 방식 (Good)	해석
학생 목록 보기	`/getStudentList`	`GET /students`	학생들(명사)을 가져와(동사)
학생 등록하기	`/add_student`	`POST /students`	학생들(명사)에 새로 추가해(동사)
3번 학생 삭제	`/del?id=3`	`DELETE /students/3`	3번 학생(명사)을 지워(동사)
3번 학생 수정	`/update_3`	`PUT /students/3`	3번 학생(명사)을 고쳐(동사)

"주소(URL)만 봐도 무엇을 다루는지 알 수 있고, 동사(Method)를 통해 무슨 짓을 할지 예측됩니다." 이것이 바로 유지보수가 쉬운 좋은 설계의 힘입니다.

6. The Future: AI Agent & Agentic Workflow (자율적 행동의 시대)

이제 API는 더 이상 개발자가 코드를 짜서 호출하는 대상에 머물지 않습니다. AI가 스스로 판단하고 실행하는 '행동의 손발'이 되었습니다.

6-1. AI 시대의 API 활용 삼총사

AI Agent (행동하는 지능): "내일 오전 10시 회의에 맞춰 대치동 맛집 예약해줘"라고 말하면, AI가 식당 예약, 캘린더, 지도 API를 스스로 조합해 업무를 완수합니다.
Function Calling (기능 호출): AI가 대화 중 "지금은 날씨 API가 필요해"라고 스스로 판단하여 도구함에서 도구를 꺼내 쓰는 기술입니다.
MCP (Model Context Protocol): 2026년 현재 가장 뜨거운 표준입니다. 어떤 API든 AI가 즉시 이해하고 꽂아 쓸 수 있게 만든 'AI 전용 유니버설 어댑터'입니다.

7. 심화: RESTful API vs MCP/Function Calling

"그럼 MCP는 RESTful API와 아예 다른 건가요?" 아니요, MCP는 RESTful API에 'AI를 위한 자기소개서'를 붙인 것과 같습니다.

구분	RESTful API (전통적)	MCP / Function Calling (미래형)
주요 사용자	사람 (개발자)	AI (Agent)
핵심 문서	Swagger (사람이 읽는 명세서)	Tool Definition (AI가 읽는 설명서)
작동 방식	정해진 순서대로 코드가 실행됨	AI가 상황에 맞춰 실시간으로 결정함
비유	키오스크: 사람이 버튼을 누름	비서: "알아서 주문해줘"라고 시킴

💡 왜 '설명(Description)'이 중요해질까요?

과거의 API는 이름만 잘 지으면 됐지만(GET /weather), AI 시대의 API는 "이 API는 섭씨온도 데이터를 제공하며, 위도와 경도 값이 반드시 필요합니다"라는 상세한 설명이 포함된 Tool Definition이 필수입니다. AI는 이 설명을 읽고 이 도구를 쓸지 말지 결정하기 때문입니다.

핵심 요약: API의 위상 변화

과거 (Passive): 사람이 프로그램을 만들기 위해 사용하던 수동적인 도구
현재/미래 (Active): AI가 세상을 변화시키기 위해 스스로 사용하는 능동적인 손발

여러분이 배우는 이 API 설계 기술은 단순한 웹 개발을 넘어, 미래의 AI 에이전트에게 어떤 '능력'을 부여할 것인지 결정하는 설계도를 그리는 작업입니다. 우리가 API를 정교하게 설계할수록, 우리의 AI 에이전트는 더 똑똑하게 세상을 조작할 수 있습니다.