API
프로그램이 다른 프로그램에게 자기 기능을 내주는 창구입니다. 부르는 쪽은 안이 어떻게 돌아가는지 몰라도 됩니다. 무엇을 부르면 무엇이 돌아오는지만 미리 정해 두면 됩니다.
상세
식당에서는 주방에 들어가지 않습니다. 메뉴판에 적힌 이름을 대고 주문하면 음식이 나옵니다.
API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 프로그램이 다른 프로그램의 기능을 부를 때 지키기로 한 약속입니다. 무엇을 부를 수 있는지, 무엇을 넘겨야 하는지, 무엇이 돌아오는지를 정합니다.
flowchart TD
A[부르는 쪽] -->|정해진 호출| B[창구]
B -->|정해진 결과| A
B -.- C[감춰진 절차]
약속에 적힌 것만 밖으로 드러납니다. 그 뒤에서 실제로 어떤 절차를 밟는지는 감춥니다. 감추기 때문에 안쪽을 고쳐도 부르는 쪽은 그대로 돕니다. 반대로 약속 자체를 바꾸면 그 창구를 부르던 쪽이 전부 손봐야 합니다.
API 는 호출 하나를 가리키는 이름이 아닙니다. 한쪽이 밖으로 내준 호출들을 묶어 부르는 이름입니다. 그래서 API 자체의 시그니처는 없습니다. 시그니처는 그 안의 개별 호출마다 있습니다.
배경
프로그램은 혼자 다 만들지 않습니다. 이미 만들어진 것을 가져다 씁니다. 그런데 가져다 쓰려면 남이 짠 코드의 속을 알아야 합니다. 속에 있는 값과 절차에 직접 손을 대고 쓰면, 그쪽이 안을 고치는 순간 이쪽이 함께 깨집니다.
그래서 기대도 되는 부분과 그렇지 않은 부분을 갈라 둘 필요가 생겼습니다. 밖으로 내주기로 한 것만 약속으로 못 박습니다. 나머지는 안쪽 사정으로 남겨 두고 언제든 바꿉니다. 이렇게 갈라 두면 양쪽이 서로를 기다리지 않고 따로 고칠 수 있습니다.
부르는 쪽과 내주는 쪽 사이에 놓인 이 경계가 API 입니다. 경계는 사람끼리의 약속이기도 합니다. 문서로 적혀 있어야 부르는 쪽이 읽고 그대로 부를 수 있습니다.
갈래
누가 무엇을 내주느냐, 곧 이 창구가 놓인 자리가 축입니다. 브라우저는 페이지의 코드에, 커널은 프로그램에, 언어와 라이브러리는 자기를 부르는 코드에 창구를 내줍니다.
웹 API
브라우저 위에서 도는 코드가 부르는 창구입니다. MDN(Mozilla Developer Network) 웹 문서는 웹용 코드를 짤 때 쓸 수 있는 웹 API 가 많다고 적습니다. 그 아래에 웹 앱이나 사이트를 만들 때 쓸 수 있을 법한 API 와 인터페이스 목록을 늘어놓습니다. 인터페이스는 객체 타입이라고 덧붙입니다. 웹 API 는 보통 자바스크립트와 함께 쓰지만 언제나 그래야 하는 것은 아니라고도 적습니다.
목록에는 Canvas API, Fetch API, Geolocation API, History API, IndexedDB API, WebSocket API, XMLHttpRequest API 같은 이름이 들어 있습니다. 그림을 그리는 것, 요청을 보내는 것, 위치를 읽는 것 처럼 하는 일은 제각각입니다. 브라우저가 내주고 코드가 부른다는 자리만 같습니다.
운영체제 API
커널이 프로그램에 내주는 창구는 시스템콜입니다. 리눅스 man 페이지의 intro(2)는 매뉴얼 2절이 리눅스 시스템콜을 설명한다고 적습니다. 시스템콜은 리눅스 커널로 들어가는 진입점이라고 부릅니다. 다만 보통은 시스템콜을 직접 부르지 않는다고 곧바로 덧붙입니다. 대부분의 시스템콜에는 커널 모드로 넘어가는 데 필요한 단계를 대신 밟아 주는 C 라이브러리 래퍼 함수가 있습니다. 그래서 시스템콜을 부르는 모습이 보통의 라이브러리 함수를 부르는 것과 같아 보입니다.
flowchart TD
A[프로그램] --> B[C 라이브러리 래퍼 함수]
B --> C[커널]
A -.->|직접 부르는 길| C
같은 문서가 2절 매뉴얼 페이지는 대개 GNU 인 C 라이브러리의 API 인터페이스와 날것의 시스템콜 양쪽을 함께 적으려 한다고 밝힙니다. 가장 흔하게는 주 설명을 C 라이브러리 인터페이스에 맞춥니다. 시스템콜과 다른 점은 NOTES 절에서 다룹니다. 창구가 두 겹으로 겹쳐 있는 자리입니다.
라이브러리 API
언어나 라이브러리가 자기 기능을 밖으로 내주는 창구도 같은 이름으로 부릅니다. 파이썬 공식 문서는 파이썬에 대한 응용 프로그래머 인터페이스가 C 와 C++ 프로그래머에게 여러 수준에서 파이썬 인터프리터에 접근할 길을 준다고 적습니다. C++ 에서도 똑같이 쓸 수 있지만 줄여서 Python/C API 라고 부른다고 밝힙니다.
쓰는 이유를 근본적으로 다른 둘로 가릅니다. 하나는 특정 목적의 확장 모듈을 짜는 것입니다. 파이썬 인터프리터를 넓히는 C 모듈입니다. 다른 하나는 더 큰 응용 프로그램 안에 파이썬을 부품으로 쓰는 것입니다. 문서는 뒤쪽을 흔히 응용 프로그램에 파이썬을 임베딩하는 기법이라고 부릅니다.
예시
GitHub REST API — 저장소 하나 읽기
GitHub 공식 문서가 REST(Representational State Transfer) API 로 적어 둔 창구입니다. 저장소 하나를 읽는 요청은 한 줄입니다.
GET /repos/{owner}/{repo}
경로 파라미터는 둘 다 필수입니다. owner 는 그 저장소를 가진 계정이고, repo 는 저장소 이름입니다. 문서는 둘 다 대소문자를 가리지 않는다고 적습니다. repo 에는 .git 확장자를 뺀 이름을 넣으라고 적습니다.
문서가 실어 둔 curl 예제는 이렇게 생겼습니다.
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2026-03-10" \
https://api.github.com/repos/OWNER/REPO
돌아올 수 있는 HTTP(HyperText Transfer Protocol) 응답 상태 코드로 200 OK, 301 Moved permanently, 403 Forbidden, 404 Resource not found 를 적어 두었습니다. 200 일 때의 응답 예제에는 id 가 1296269, name 이 Hello-World, full_name 이 octocat/Hello-World 로 들어 있습니다.
권한 조건도 같이 적혀 있습니다. 세분화된 토큰으로 이 창구를 부르려면 Metadata 저장소 권한을 읽기로 가지고 있어야 합니다. 다만 공개 자원만 요청한다면 인증 없이도, 앞서 말한 권한 없이도 쓸 수 있다고 덧붙입니다.
파이썬 표준 라이브러리 — os.listdir()
같은 프로세스 안에서 부르는 호출 한 벌입니다.
os.listdir(path='.')
파이썬 공식 문서는 이 호출이 path 가 가리키는 디렉터리 안 항목들의 이름을 담은 리스트를 돌려준다고 적습니다. 리스트의 순서는 임의입니다. 디렉터리에 '.' 과 '..' 이 있더라도 그 둘은 넣지 않습니다.
돌아오는 값의 타입은 넘긴 값의 타입을 따라갑니다. path 가 bytes 면, PathLike 인터페이스를 거쳐 간접적으로 넘긴 경우까지 포함해 돌아오는 파일 이름도 bytes 입니다. 그 밖의 경우에는 전부 str 입니다.
정해 두지 않은 자리도 문서가 밝힙니다. 이 함수가 도는 동안 디렉터리에서 파일이 지워지거나 새로 생기면, 그 파일의 이름이 결과에 들어갈지는 정해져 있지 않습니다.
관련 항목
창구를 내주는 실행 환경
커널 · 운영체제 · 브라우저 · 인터프리터 · 프로세스 · 라이브러리 · 표준 라이브러리 · 프레임워크
이 창구를 실제로 부르는 방식
래퍼 함수 · 확장 모듈 · 임베딩
위에 얹히는 통신 프로토콜
낱개 호출을 이루는 조각
시그니처 · 엔드포인트 · 요청 메서드 · GET · 상태 코드 · HTTP 403 · JSON(JavaScript Object Notation) · 인증과 인가 · 인증 · 권한 · 액세스 토큰 · RFC(Request for Comments) 9110 · 시스템콜 · 디렉터리 · PathLike
약속을 적어 두는 표준과 문서
명세 문서 · OpenAPI · API 설계 · MDN
약속을 바꿀 때 지키는 규칙
하위 호환 · 버전관리 · 시맨틱 버저닝 · 폐기 예고 · 브레이킹 체인지
헷갈리는 이웃
ABI(Application Binary Interface) · 인터페이스 · SDK(Software Development Kit)
실제로 이 창구를 구현하거나 쓴 사례
GitHub · 리눅스 · 파이썬 · C++ · 자바스크립트 · GNU · curl
웹 API 아래 이름 붙은 낱개 종류
Canvas API · Fetch API · Geolocation API · History API · IndexedDB API · WebSocket API · XMLHttpRequest API
잦은 호출에서 나는 장애
여러 번 부를 때 지키는 규칙
다른 이름: Application Programming Interface · application programming interface · 응용 프로그램 인터페이스