API
프로그램끼리 서로를 부르는 창구. 「API 공개」는 「다른 앱들이 이 AI를 갖다 쓸 수 있게 됐다」는 뜻.
쉽게 말하면
API(Application Programming Interface)는 프로그램이 다른 프로그램을 부르는 창구입니다. 식당의 주문 창구라고 생각하면 됩니다 — 주방(AI 모델)이 어떻게 돌아가는지 몰라도, 정해진 방식으로 주문서를 넣으면 요리가 나옵니다.
AI 뉴스에서 「API를 공개했다」는 「다른 앱들이 이 AI를 갖다 쓸 수 있게 됐다」는 뜻입니다. 번역 앱, 글쓰기 도우미, 고객센터 챗봇 — 시중의 수많은 AI 서비스가 사실 오픈AI·앤스로픽·구글의 API 창구에 주문을 넣어 돌아갑니다. 앱을 만든 회사와 AI를 만든 회사가 다른 경우가 대부분인 거죠.
요금이 붙는 지점이라 돈 이야기와 자주 같이 나옵니다. API 가격은 토큰 단위로 매겨지고(「100만 토큰당 몇 달러」), 가격 인하 발표는 곧 「AI 앱 만들기가 싸졌다」는 업계 뉴스가 됩니다. 챗봇 화면에서 쓰는 소비자 요금제와 API 요금은 별개라는 것도 알아 두면 기사가 덜 헷갈립니다.
기사에서 이렇게 나와요
「신모델 API 가격을 절반으로 인하」 — 개발사들의 원가가 내려갔다는 뜻이라, 후속으로 각종 AI 앱의 기능 확대 소식이 따라오곤 합니다.
직접 해보기
- API의 민낯부터 봅니다. 브라우저 주소창에 api.github.com 을 쳐 보세요 — 사람용 화면 대신 프로그램용 응답(JSON이라는 데이터 꾸러미)이 그대로 나옵니다. 프로그램들은 서로 이런 모습으로 대화합니다.
- AI API를 코드 없이 체험하려면 「OpenAI Playground」나 「Anthropic Console」을 검색해 들어가 보세요 — 챗봇 화면 없이 모델을 직접 호출하는 개발자용 조작판입니다.
- 거기서 시스템 프롬프트·응답 길이 같은 조절 손잡이를 만져 보세요. 챗봇 앱과 이 화면의 차이가 곧 「완제품」과 「부품(API)」의 차이입니다 — 세상의 AI 앱들은 이 부품을 조립한 것들입니다.
깊이 알아보기
API는 두 프로그램이 서로의 내부를 열어 보지 않고도, 정해진 창구와 약속을 통해 일을 주고받게 하는 연결 규칙입니다.
API는 소프트웨어가 기능과 데이터를 요청하고 결과를 받는 방법을 정의한 인터페이스입니다. 어디로 무엇을 보내고, 어떤 인증을 거치며, 성공과 실패를 어떤 형식으로 돌려받는지 계약으로 정해 사람과 시스템이 독립적으로 개발되고도 안전하게 협력할 수 있게 합니다.
3분 요약
- API의 핵심은 요청과 응답의 계약입니다. 호출하는 쪽은 정해진 연산과 입력 형식을 따르고, 제공하는 쪽은 약속된 결과나 오류를 반환합니다. HTTP API에서는 엔드포인트, 메서드, 헤더와 본문이 이 계약을 표현하지만 모든 API가 HTTP인 것은 아닙니다.
- 운영 가능한 API에는 인증과 권한, 호출량 제한, 오류 규칙, 버전 정책이 필요합니다. 같은 요청의 재시도가 중복 결제나 중복 생성을 일으키지 않도록 메서드의 멱등성을 이해하고 필요하면 멱등성 키 같은 장치를 사용합니다.
- AI 모델 API도 같은 원리로 동작합니다. 애플리케이션이 모델과 입력, 도구, 출력 조건을 보내면 서비스가 생성 결과와 사용량 또는 오류를 돌려줍니다. 비밀 키는 브라우저나 앱 코드에 넣지 않고 서버의 안전한 비밀 저장소에서 관리해야 합니다.
왜 지금 알아야 하나
제품이 여러 서비스의 조합으로 만들어진다
결제, 지도, 로그인, 검색과 메시징을 모두 직접 만들기보다 전문 서비스의 API를 연결하는 제품이 많아졌습니다. 약속된 인터페이스가 있으면 각 시스템은 내부 구현을 독립적으로 바꾸면서도 정해진 계약을 통해 협력할 수 있습니다.
AI 기능도 API로 제품 안에 들어온다
대화 화면에서 모델을 직접 쓰는 것과 달리, 제품은 API로 고객 문의를 분류하고 문서를 요약하거나 이미지를 분석합니다. 모델 호출 전후의 인증, 데이터 처리, 비용 제한과 오류 복구까지 설계해야 실험이 안정적인 기능으로 바뀝니다.
자동화가 늘수록 실패 규칙이 중요해진다
사람은 오류 메시지를 보고 판단할 수 있지만 프로그램은 상태 코드와 구조화된 응답으로 다음 행동을 결정합니다. 일시적 장애인지 잘못된 입력인지, 재시도해도 안전한지 구분하지 못하면 작은 통신 오류가 중복 처리나 연쇄 장애로 번질 수 있습니다.
어떻게 작동하나
1. 제공자가 호출 계약을 정의한다
API는 사용할 수 있는 기능, 입력 필드, 자료형, 필수값과 반환 형식을 문서화합니다. HTTP API라면 자원의 주소인 엔드포인트와 조회, 생성, 변경, 삭제 같은 의도를 나타내는 메서드를 함께 정의합니다. 라이브러리 API, 운영체제 API와 프로세스 간 통신처럼 다른 호출 방식도 같은 계약 원리를 따릅니다.
2. 호출자가 인증 정보와 요청을 보낸다
클라이언트는 필요한 매개변수와 본문, 인증 정보를 계약에 맞춰 전달합니다. 인증은 누가 호출하는지 확인하고 권한 부여는 그 주체가 어떤 데이터와 기능을 쓸 수 있는지 제한합니다. API 키와 토큰은 소스 코드, 공개 저장소, 브라우저 번들에 넣지 않고 서버 환경이나 비밀 관리 서비스에서 주입하며 로그에서도 가립니다.
3. 서버가 처리 결과나 오류를 반환한다
제공자는 요청을 검증하고 작업한 뒤 성공 결과 또는 기계가 해석할 수 있는 오류를 돌려줍니다. HTTP에서는 상태 코드와 응답 본문이 실패 종류를 전달합니다. 호출량 제한에 걸렸는지, 인증이 잘못됐는지, 서버가 일시적으로 실패했는지 구분해야 클라이언트가 수정, 대기 또는 재시도를 선택할 수 있습니다.
4. 재시도와 변화에 견디도록 운영한다
네트워크 응답을 받지 못했다고 작업이 실행되지 않은 것은 아닐 수 있습니다. 안전한 재시도를 위해 멱등적인 연산을 사용하거나 생성 요청에 멱등성 키를 붙여 중복 처리를 막습니다. 호출량 제한에는 지수 백오프와 무작위 지연으로 대응하고, 호환되지 않는 변경은 버전 정책과 폐기 일정으로 알립니다.
흐름 한눈에 보기
기능 계약 확인 → 엔드포인트·연산 선택 → 서버에서 인증 정보와 입력 구성 → API 요청 → 인증·권한·호출량 검증 → 작업 실행 → 성공 결과 또는 구조화된 오류 응답 → 안전한 재시도·기록·버전 대응
도입 전과 후
이전: 사람을 위한 화면을 프로그램이 흉내 낸다
한 서비스의 데이터를 얻기 위해 다른 프로그램이 웹 화면을 열고 버튼 위치와 표시 문구를 해석합니다. 화면 구조가 조금만 바뀌어도 자동화가 깨지고, 입력과 오류의 의미도 안정적으로 구분하기 어렵습니다.
이후: 정해진 계약으로 기능을 호출한다
서비스는 데이터 조회나 작업 생성을 위한 API를 제공하고 호출자는 문서화된 형식으로 요청합니다. 화면 디자인이 바뀌어도 API 계약이 유지되면 통합은 계속 동작하며, 성공과 실패도 정해진 코드와 필드로 처리할 수 있습니다.
운영: 실패와 변경까지 계약에 포함한다
정상 응답만 연결하는 데서 끝내지 않고 시간 초과, 호출량 제한, 잘못된 입력과 서비스 장애를 각각 다룹니다. 요청 식별자와 멱등성 정책을 두고, 새 버전 전환 기간과 폐기 일정을 관리해 배포와 재시도가 데이터 중복으로 이어지지 않게 합니다.
예시로 이해하기
온라인 상점의 주문 생성 API
상점 서버가 주문 엔드포인트에 상품, 수량과 배송 정보를 보내면 결제 서비스는 주문 식별자와 상태를 반환합니다. 응답이 오기 전에 연결이 끊기면 같은 요청을 무작정 다시 보내 중복 주문이 생길 수 있습니다. 클라이언트가 고유한 멱등성 키를 보내고 서버가 처리 결과를 기억하면 같은 작업의 재시도를 하나의 주문으로 다룰 수 있습니다.
AI 모델을 호출하는 문서 요약 기능
애플리케이션 서버는 모델 API에 사용할 모델, 문서와 출력 조건을 보내고 생성된 요약과 사용량 정보를 받습니다. 모델 서비스의 키는 사용자의 브라우저가 아니라 서버에서만 읽습니다. 입력이 너무 크거나 호출량 제한에 걸린 오류는 사용자 입력 오류와 구분하며, 비용과 지연을 감시하고 제공자의 모델 변경 공지를 따라 평가를 다시 실행합니다.
직접 해보기
1. 공식 문서에서 한 연산을 고른다
공개 API 문서에서 데이터 조회처럼 영향이 작은 기능 하나를 선택합니다. 엔드포인트, 메서드, 필수 입력, 인증 방식과 성공 응답을 표로 정리합니다.
2. 정상 요청과 오류 요청을 비교한다
공식 예제나 개발용 환경에서 유효한 요청을 보내 결과를 확인한 뒤 필수 필드를 하나 제외해 봅니다. 상태 코드, 오류 유형과 메시지가 어떻게 달라지는지 기록하고 프로그램이 분기할 기준을 찾습니다.
3. 비밀과 권한의 경계를 점검한다
인증 정보가 저장소, 클라이언트 코드, URL과 로그에 노출되지 않는지 확인합니다. 개발과 운영의 키를 분리하고 필요한 기능에만 접근하는 최소 권한을 부여하며, 노출이 의심되면 즉시 폐기하고 교체합니다.
4. 재시도 정책을 작성한다
각 오류를 입력 수정, 인증 갱신, 지연 후 재시도와 즉시 중단으로 나눕니다. 작업 생성처럼 부작용이 있는 요청은 멱등성 보장 여부를 확인하고, 호출량 제한 응답에는 서버가 제공한 대기 정보와 지수 백오프를 적용합니다.
한계와 주의점
계약이 있어도 네트워크는 실패한다
시간 초과, 연결 중단과 일시적 서버 장애는 정상적인 운영 조건입니다. 응답을 받지 못한 상태와 작업이 실행되지 않은 상태를 같다고 보면 안 되며, 관측 가능성, 시간 제한과 안전한 재시도 정책이 필요합니다.
인증은 안전한 사용 전체를 보장하지 않는다
유효한 키를 가진 호출도 과도한 권한으로 데이터에 접근하거나 큰 비용을 만들 수 있습니다. 최소 권한, 사용량 한도, 키 순환, 감사 로그와 입력 검증을 함께 적용해야 하며 비밀이 노출되면 숨기는 것으로 끝내지 말고 폐기해야 합니다.
버전과 제공자 의존성을 관리해야 한다
응답 필드, 모델 동작이나 정책이 바뀌면 기존 통합이 영향을 받을 수 있습니다. 공식 변경 기록을 확인하고 계약 테스트와 평가를 유지하며, 폐기되는 버전에서 이동할 시간을 확보해야 합니다. API가 있다고 해서 모든 기능이 영구히 같은 형태로 제공되는 것은 아닙니다.
자주 묻는 질문
API는 모두 웹에서 HTTP로 호출하나요?
아닙니다. 웹 API가 널리 쓰이지만 프로그래밍 언어의 라이브러리, 운영체제 함수, 데이터베이스 드라이버와 프로세스 간 통신도 API입니다. HTTP의 엔드포인트와 메서드는 API 계약을 구현하는 대표적인 방식 중 하나입니다.
API 키를 앱이나 웹페이지에 넣어도 되나요?
공개되어도 되는 식별자가 아니라 비밀 키라면 넣으면 안 됩니다. 배포된 앱과 브라우저 코드는 사용자가 확인할 수 있으므로 키는 서버의 환경 변수나 비밀 관리 서비스에 보관하고 서버가 대신 API를 호출해야 합니다. 키마다 최소 권한과 사용량 제한을 적용하고 로그에서는 값을 가려야 합니다.
오류가 나면 같은 요청을 바로 다시 보내면 되나요?
오류 종류와 작업의 멱등성에 따라 다릅니다. 잘못된 입력이나 권한 오류는 재시도보다 수정이 먼저이고, 일시적 장애와 호출량 제한은 대기 후 재시도할 수 있습니다. 결제나 생성처럼 부작용이 있는 요청은 제공자의 멱등성 지원을 확인하지 않으면 중복 처리될 수 있습니다.
출처
- OpenAI API Reference: Introduction — OpenAI
- RFC 9110: HTTP Semantics — Internet Engineering Task Force
- RFC 9457: Problem Details for HTTP APIs — Internet Engineering Task Force
- OpenAPI Specification — OpenAPI Initiative
API와 MCP, 뭐가 다른가
사람이 짜 넣는 개별 창구냐, AI가 알아서 쓰는 공용 규격이냐
둘 다 「AI를 바깥과 잇는다」고 설명되기 때문에 같은 말의 다른 이름처럼 들립니다. 그런데 API는 서비스마다 제각각인 개별 창구이고, MCP는 그 창구들의 모양을 통일하자는 약속입니다. 층이 다릅니다 — MCP를 지원하는 서비스도 그 속에서는 결국 API를 씁니다.
| 구분 | API | MCP |
|---|---|---|
| 무엇인가 | 서비스마다 따로 있는 주문 창구 | 창구의 모양을 통일한 공용 규격 |
| 누가 쓰나 | 사람이 코드를 짜서 부른다 | AI가 연결된 도구를 스스로 골라 쓴다 |
| 부르는 방향 | 대개 앱이 AI를 갖다 쓴다 | 대개 AI가 바깥 도구를 갖다 쓴다 |
| 붙이는 비용 | 서비스 100개면 연결 100개를 따로 만든다 | 규격에 맞춰 한 번 만들면 어느 AI에나 꽂힌다 |
| 비유 | 식당의 주문 창구 | USB-C 단자 규격 |
| 기사에서 | 가격 인하·사용량 같은 돈 이야기와 붙는다 | 에이전트·커넥터 같은 연결 이야기와 붙는다 |
가를 때는앱이 AI를 갖다 쓰는 이야기면 API, AI가 내 도구와 데이터를 갖다 쓰는 이야기면 MCP입니다.
API와 SDK, 뭐가 다른가
부르는 창구냐, 그 창구를 쓰기 쉽게 만든 도구상자냐
발표가 늘 같이 나옵니다. 「API와 SDK를 공개했다」는 문장에서 둘이 각각 무엇인지는 아무도 설명해 주지 않습니다. 관계는 단순합니다 — API가 먼저 있고, SDK는 그 API를 편하게 쓰라고 회사가 덧붙여 만든 것입니다. SDK 없이 API만 써도 되지만, 그 반대는 성립하지 않습니다.
| 구분 | API | SDK |
|---|---|---|
| 정체 | 주문을 넣는 창구 그 자체 | 그 창구용 부품·설명서·예제 묶음 |
| 없어도 되나 | 없으면 아무것도 못 한다 | 없어도 된다. 손이 더 갈 뿐이다 |
| 누구 것인가 | 언어와 무관하다. 규칙만 맞추면 된다 | 언어별로 따로 나온다. 파이썬용·자바스크립트용 |
| 발표의 뜻 | 이제 남들이 우리 기술을 갖다 쓸 수 있다 | 갖다 쓰기가 훨씬 쉬워졌다. 개발자를 데려오겠다는 신호다 |
| 비유 | 주문 창구 | 주문을 대신 넣어 주는 도우미 세트 |
가를 때는기능이 열렸다는 이야기면 API, 그 기능을 쓰기 쉬워졌다는 이야기면 SDK입니다.
함께 볼 용어
이 용어가 나온 기사
아직 이 용어를 다룬 기사가 없습니다. 새 기사가 나오면 여기 자동으로 붙습니다.