API란 무엇인가: 요청·응답·API 키까지 쉽게 이해하기

기준: MDN Web Docs, Anthropic API 문서, Claude 고객센터 문서, Blender Python API 문서. 2026년 9월에 확인했습니다.

API는 프로그램이 다른 프로그램에게 일을 부탁하는 정해진 창구입니다. 부탁하는 쪽은 정해진 형식으로 요청을 보내고, 받는 쪽은 정해진 형식으로 응답을 돌려줍니다. 이 글에서는 API가 무엇인지 콘센트 비유로 이해하고, 요청과 응답이 어떻게 생겼는지, 결과 번호(상태 코드, 200·404 등)는 무슨 뜻인지, 그리고 API 키를 왜 비밀번호처럼 지켜야 하는지까지 차례로 정리합니다. 코딩을 해 본 적이 없어도 읽을 수 있게 썼습니다.

날씨를 직접 재지 않는 날씨 앱

휴대폰의 날씨 앱을 열면 지금 기온과 내일 예보가 바로 나옵니다. 그런데 휴대폰 안에 온도계나 기상 레이더가 들어 있는 것은 아닙니다. 앱은 날씨 정보를 가진 다른 컴퓨터(서버)에게 "이 지역 날씨 알려 주세요"라고 물어보고, 받은 답을 화면에 예쁘게 그려 줄 뿐입니다.

AI 채팅 앱도 비슷합니다. 앱 화면에 질문을 입력하면, 앱은 AI 모델이 돌아가는 서버에 질문을 보내고 답을 받아 옵니다. 이렇게 프로그램이 다른 프로그램에게 묻고 답을 받는 약속된 통로가 바로 API입니다.

API의 뜻: 프로그램을 위한 약속

API는 Application Programming Interface의 줄임말입니다. 우리말로 풀면 "응용 프로그램이 쓰는 연결 창구" 정도입니다. MDN(Mozilla가 운영하는 개발자 문서)의 설명을 간추리면 세 가지입니다.

• 소프트웨어 안에 있는 기능과 규칙의 묶음입니다.
• 사람이 누르는 화면(UI, 사용자 화면)이 아니라 다른 소프트웨어가 그 프로그램의 기능을 불러 쓸 수 있게 해 줍니다.
• 기능을 주는 쪽과 쓰는 쪽 사이의 간단한 계약입니다.

"계약"은 이런 뜻입니다. 주는 쪽은 "이런 형식으로 부탁하면 이런 형식으로 답해 주겠다"고 약속하고, 쓰는 쪽은 그 형식만 지키면 됩니다. 안쪽이 어떻게 만들어졌는지는 몰라도 됩니다. API는 복잡한 코드를 감춰 두고 더 쉬운 사용법을 대신 제공합니다.

비유: 벽의 콘센트

API는 벽의 콘센트와 같습니다.

우리는 헤어드라이어를 쓸 때 전선을 벽 속 전력망에 직접 이어 붙이지 않습니다. 그렇게 하면 번거롭고, 전기 기술자가 아니면 어렵고 위험합니다. 대신 규격에 맞는 플러그를 콘센트에 꽂기만 하면 됩니다. 발전소가 어디 있는지, 벽 속 배선이 어떻게 되어 있는지는 몰라도 전기를 쓸 수 있습니다.

3D 그래픽을 만들 때도 마찬가지입니다. 그래픽 장치를 직접 다루는 어려운 저수준 코드(C, C++ 등)를 짜는 대신, JavaScript나 Python 같은 언어로 된 API를 쓰는 편이 훨씬 쉽습니다. 이 비유를 인터넷 서비스에 맞춰 옮기면 다음과 같습니다.

흔히 쓰는 또 다른 비유는 식당 주문입니다. 손님(내 앱)은 주방(서버) 안을 볼 수 없지만, 메뉴판(API 문서)에 적힌 대로 주문(요청)하면 음식(응답)이 나옵니다. 메뉴판에 없는 음식을 시키면 "그런 메뉴는 없어요"라는 답이 돌아옵니다. 뒤에서 볼 상태 코드가 바로 이런 답입니다.

요청과 응답의 생김새

인터넷을 거치는 API는 대부분 HTTP라는 규칙으로 대화합니다. HTTP는 웹에서 데이터를 주고받는 기본 규약입니다. 웹 페이지를 여는 것도 HTTP로 이루어집니다. HTTP에서는 부탁하는 쪽(클라이언트)이 먼저 요청을 보내고, 서버는 그 요청에 답합니다. 서버가 먼저 말을 거는 구조가 아닙니다.

요청과 응답에는 각각 정해진 칸이 있습니다.

메서드: 하고 싶은 일

메서드는 요청의 동사입니다. 자주 보는 것은 네 가지입니다.

• GET: 자료를 가져오기만 합니다. 예: 날씨 정보 보기
• POST: 서버에 데이터를 보냅니다. 서버의 상태가 바뀌는 경우가 많습니다. 예: 질문 보내기, 글 올리기
• PUT: 자료를 통째로 새것으로 바꿉니다.
• DELETE: 자료를 지웁니다.

JSON: 데이터를 적는 공통 양식

요청과 응답의 본문은 흔히 JSON이라는 형식으로 적습니다. JSON은 이름과 값을 짝지어 적는 텍스트 형식입니다. 이름은 JavaScript에서 왔지만 다른 프로그래밍 언어에서도 널리 씁니다. 예를 들어 날씨 정보라면 이런 모양이 될 수 있습니다. 아래 값은 설명을 위한 예시입니다.

{
  "city": "Seoul",
  "temperature": 21,
  "sky": "clear"
}

사람이 읽어도 대강 뜻을 알 수 있고, 프로그램도 쉽게 읽을 수 있어서 널리 쓰입니다.

상태 코드: 결과를 알려 주는 번호

서버는 응답에 세 자리 번호를 붙여서 결과를 알려 줍니다. 이 번호를 상태 코드라고 합니다. 성공도 번호로 알려 주므로, 모든 번호가 오류는 아닙니다. 첫 자리로 큰 뜻을 알 수 있습니다. 묶음은 다섯 가지입니다.

그중 자주 만나는 번호는 다음과 같습니다.

오류 메시지에 이 번호가 보이면 문제가 내 쪽(4xx)인지 서버 쪽(5xx)인지 먼저 가늠할 수 있습니다. 401은 이름이 "Unauthorized(권한 없음)"이지만, 실제 뜻은 "누구인지 확인되지 않음"에 가깝습니다. API 키를 빠뜨리거나 잘못 넣었을 때 자주 보는 번호입니다.

REST API라는 말

API 설명서에서 "REST API"라는 말을 자주 봅니다. 입문 단계에서는 "보통의 웹 방식(HTTP)으로 부를 수 있는 API"라고 이해하면 됩니다. 다만 이름과 달리 REST의 설계 원칙을 모두 지키지 않는 경우도 있습니다.

실제 예: AI 채팅 앱이 Claude API를 부르는 흐름

Anthropic의 Claude API를 예로 들어 보겠습니다. Claude API는 https://api.anthropic.com에 있는 REST 방식의 API이고, 대화를 주고받는 Messages API는 POST /v1/messages 경로를 씁니다.

AI 채팅 앱이 질문 하나를 처리하는 흐름은 다음과 같습니다.

1. 사용자가 앱에 질문을 입력합니다.
2. 앱이 질문을 JSON에 담아 POST /v1/messages로 요청을 보냅니다.
3. 요청 헤더에는 신분증 역할의 API 키, API 버전, 데이터 형식이 들어갑니다.
4. Claude API가 답을 만들어 JSON으로 돌려줍니다.
5. 앱이 받은 답을 화면에 보여 줍니다.

요청의 뼈대를 표로 정리하면 이렇습니다. 헤더 이름과 값은 Anthropic API 문서 기준입니다. 키 자리에는 가짜 자리표시자를 넣었습니다.

실제 키는 절대 글이나 코드에 그대로 적지 않습니다. Python, TypeScript 같은 언어용 공식 SDK(개발 도구 모음)도 있습니다. SDK를 쓰면 인증, 버전, 형식 헤더를 도구가 알아서 붙여 줍니다.

API는 보통 무제한이 아닙니다. Claude API에는 분당 요청 수, 분당 토큰(글자 조각) 수, 월 지출 한도 같은 제한이 사용 등급별로 정해져 있습니다. 너무 자주 부르면 앞에서 본 429 응답을 받을 수 있습니다. 구체적인 수치와 요금은 바뀔 수 있으니 공식 문서에서 직접 확인하세요. 또 같은 Claude 모델을 Anthropic에서 직접 부를 수도 있고, AWS, Google Cloud, Microsoft Azure 같은 클라우드 플랫폼을 통해 부를 수도 있습니다. 플랫폼마다 쓸 수 있는 기능은 다를 수 있습니다.

인터넷 밖의 API

API라고 하면 인터넷 주소만 떠올리기 쉽지만, 프로그램 안쪽의 기능을 여는 API도 많습니다.

• 브라우저 API: 웹 브라우저 안에 들어 있는 API입니다. 예를 들어 위치 API(Geolocation API)는 기기의 위치 정보를 가져옵니다. 이것을 지도 서비스의 API와 함께 쓰면 "내 주변 관광지"를 지도에 보여 줄 수 있습니다.
• 외부 API: 다른 회사가 인터넷으로 제공하는 API입니다. Google Maps API, YouTube API 등이 있습니다.
• 프로그램 API: 3D 프로그램 Blender에도 Python API가 있습니다. bpy.data로 장면 속 물체, 재질 같은 데이터를 읽고 바꾸고, bpy.ops로 화면에서 버튼을 누르는 것과 같은 동작을 스크립트로 실행합니다. 스크립트는 사용자 화면, 가져오기·내보내기, 장면 조작, 자동화 등에 씁니다.

Blender를 화면 없이 실행하고 Python 스크립트로 장면을 만드는 것도 Blender Python API를 쓰는 한 예입니다. 이 흐름은 Blender와 AI 연결에서 설명합니다.

비밀번호처럼 다루는 API 키

API에는 보안 장치가 함께 붙습니다. 일부 최신 브라우저 API는 암호화된 연결(HTTPS)에서만 동작하고, 알림(Notifications) API처럼 사용자에게 먼저 허락을 묻는 것도 있습니다. 인터넷 서비스 API에서 가장 흔히 만나는 보안 장치는 API 키입니다.

많은 API는 누가 요청을 보냈는지 확인하려고 API 키를 요구합니다. API 키는 긴 문자열로 된 디지털 열쇠입니다. Claude 고객센터는 API 키를 신용카드 번호처럼 다루라고 안내합니다. 남이 내 키를 쓰면 그 요청의 요금이 내 계정으로 나가기 때문입니다.

기본 수칙은 다음과 같습니다.

1. 아무 데도 붙여 넣지 않습니다. 공개 게시판, 이메일, 고객 지원 문의에도 키를 넣지 않습니다.
2. 코드에 직접 적지 않습니다. 키가 새는 가장 흔한 경로는 공개 코드 저장소(예: 공개 GitHub 저장소)에 키가 적힌 파일을 그대로 올리는 실수입니다. 내 컴퓨터에서 쓸 때는 키를 .env 파일에 따로 두고, 그 파일을 .gitignore(저장소에 올리지 않을 파일 목록)에 넣어 빼 둡니다. 외부 서비스에 키를 넣어야 할 때는 코드나 설정 파일이 아니라 그 서비스의 암호화된 비밀 값(secret) 기능에 넣습니다.
3. 샌 것 같으면 바로 바꿉니다. Claude API 키라면 순서는 이렇습니다.
   • Claude Console의 API 키 화면에서 해당 키를 즉시 삭제(Delete API Key)합니다.
   • 같은 페이지의 Create Key로 새 키를 만들어 바꿔 끼웁니다.
   • 새 키는 비밀 값 관리 도구처럼 안전한 곳에 보관하고, 버전 관리(코드 저장소)에는 넣지 않습니다.
   • 그 뒤에도 이상한 사용이 계속 보이면 지원팀에 문의합니다.

이 글에서는 키가 들어갈 자리에 YOUR_API_KEY_HERE 같은 가짜 자리표시자를 썼습니다.

흔한 오해 정리

한 줄 정리

API는 프로그램끼리 대화하는 약속. 한쪽이 정해진 형식으로 요청하면 다른 쪽이 상태 코드와 함께 응답. 이 구조만 알아 두어도 앱 설정 화면이나 오류 메시지에서 "API"라는 말을 만났을 때 무슨 일이 일어나는지 짐작할 수 있습니다.

참고 자료

• MDN Glossary: API
• MDN, Introduction to web APIs
• MDN, Overview of HTTP
• MDN, HTTP request methods
• MDN, HTTP response status codes
• MDN, Working with JSON
• MDN Glossary: REST
• Anthropic, API overview
• Claude Help Center, API Key Best Practices
• Claude Help Center, API 키가 유출된 것 같을 때
• Blender Python API, Overview