API란 무엇인가?¶
프로그램은 어떻게 서로 대화할까?¶
우리가 스마트폰으로 날씨 앱을 열면, 앱은 어딘가에서 오늘의 날씨 데이터를 가져옵니다.
카카오맵에서 음식점을 검색하면, 지도 위에 핀이 찍힙니다.
이 모든 게 가능한 이유가 바로 API 덕분입니다.
API란?¶
API = Application Programming Interface
직역하면 "응용 프로그램 프로그래밍 인터페이스"인데, 쉽게 말하면:
프로그램과 프로그램이 대화하는 방법(규칙)
레스토랑 비유¶
| 역할 | 레스토랑 | 소프트웨어 |
|---|---|---|
| 손님 | 음식을 주문하는 사람 | 우리가 만드는 앱 |
| 메뉴판 | 주문할 수 있는 것들 | API 문서 |
| 웨이터 | 주문을 전달하는 사람 | API |
| 주방 | 음식을 만드는 곳 | 서버 / 데이터베이스 |
손님(앱)은 주방(서버) 내부를 알 필요 없이, 웨이터(API)에게 주문(요청)만 하면 됩니다.
웨이터는 주방에서 결과를 가져와 손님에게 돌려줍니다.
인터페이스(Interface)란?¶
"Interface"는 두 세계가 만나는 접점입니다.
사람 ←→ [버튼·화면] ←→ 컴퓨터 # UI (User Interface)
앱 ←→ [API] ←→ 서버 # API (Application Programming Interface)
- UI: 사람이 프로그램을 다루는 접점 (버튼, 화면)
- API: 프로그램이 다른 프로그램을 다루는 접점
내부 구현은 몰라도 됩니다. 약속된 방식으로 요청하면 결과가 옵니다.
실제 API 예시¶
날씨 API¶
요청: "서울의 오늘 날씨 알려줘"
응답: { "city": "서울", "temp": 22, "condition": "맑음" }
지도 API (카카오맵, 구글맵)¶
요청: "강남역 좌표 알려줘"
응답: { "lat": 37.498, "lng": 127.028 }
번역 API¶
요청: "Hello를 한국어로 번역해줘"
응답: { "result": "안녕하세요" }
앱 개발자는 날씨 데이터를 직접 수집하거나, 지도를 직접 만들거나, 번역 엔진을 만들 필요가 없습니다.
API를 통해 이미 만들어진 기능을 빌려 씁니다.
HTTP API (Web API)¶
현대 대부분의 API는 HTTP 프로토콜 위에서 동작합니다. 웹 브라우저가 웹 서버와 통신하는 바로 그 방식입니다.
요청(Request) 구조¶
[메서드] [주소(URL)]
헤더(Header): 추가 정보
본문(Body): 전달할 데이터
HTTP 메서드¶
| 메서드 | 의미 | 예시 |
|---|---|---|
GET |
데이터 가져오기 | 게시글 목록 조회 |
POST |
데이터 생성하기 | 회원가입, 글 작성 |
PUT |
데이터 수정하기 | 프로필 수정 |
DELETE |
데이터 삭제하기 | 게시글 삭제 |
요청 예시¶
GET https://api.weather.com/v1/current?city=seoul
POST https://api.myapp.com/users
Content-Type: application/json
{
"name": "지민",
"email": "[email protected]"
}
응답(Response)과 상태 코드¶
서버는 요청을 처리하고 상태 코드와 함께 응답합니다.
HTTP/1.1 200 OK
Content-Type: application/json
{ "id": 42, "name": "지민", "email": "[email protected]" }
주요 상태 코드¶
| 코드 | 의미 | 비유 |
|---|---|---|
200 OK |
성공 | "네, 여기 있습니다" |
201 Created |
생성 성공 | "새로 만들었습니다" |
400 Bad Request |
잘못된 요청 | "주문이 이상해요" |
401 Unauthorized |
인증 필요 | "신분증이 없으면 안 돼요" |
404 Not Found |
없음 | "그런 메뉴는 없어요" |
500 Server Error |
서버 오류 | "주방에서 문제가 생겼어요" |
JSON — API의 공용 언어¶
API는 데이터를 주고받을 때 주로 JSON 형식을 씁니다.
JSON = JavaScript Object Notation
{
"name": "지민",
"age": 17,
"subjects": ["수학", "영어", "Python"],
"address": {
"city": "서울",
"district": "강남"
}
}
JSON 규칙¶
| 요소 | 표현 | 예시 |
|---|---|---|
| 문자열 | 큰따옴표 | "hello" |
| 숫자 | 그대로 | 42, 3.14 |
| 참/거짓 | 소문자 | true, false |
| 없음 | 소문자 | null |
| 배열 | 대괄호 | [1, 2, 3] |
| 객체 | 중괄호 | {"key": "value"} |
Python으로 API 사용해보기¶
Python의 requests 라이브러리로 API를 직접 호출할 수 있습니다.
import requests
# GET 요청: 공개 API에서 데이터 가져오기
response = requests.get("https://jsonplaceholder.typicode.com/posts/1")
print(response.status_code) # 200
print(response.json()) # 딕셔너리로 변환된 JSON
# 결과 예시
{
'userId': 1,
'id': 1,
'title': 'sunt aut facere repellat...',
'body': 'quia et suscipit...'
}
응답 데이터 활용¶
import requests
response = requests.get("https://jsonplaceholder.typicode.com/users/1")
user = response.json()
print(user["name"]) # Leanne Graham
print(user["email"]) # [email protected]
print(user["address"]["city"]) # Gwenborough
API Key — 열쇠가 있어야 들어갑니다¶
많은 API는 API Key를 요구합니다. 누가 요청하는지 파악하고, 요금을 청구하거나 남용을 방지하기 위해서입니다.
import requests
API_KEY = "your_api_key_here"
response = requests.get(
"https://api.openweathermap.org/data/2.5/weather",
params={
"q": "Seoul",
"appid": API_KEY,
"units": "metric"
}
)
data = response.json()
print(f"서울 기온: {data['main']['temp']}°C")
API Key는 비밀번호처럼 관리해야 합니다. 코드에 직접 넣지 말고 환경변수나 별도 파일로 관리합니다.
REST API¶
현재 가장 널리 쓰이는 API 설계 방식입니다.
REST = Representational State Transfer
REST의 핵심 원칙¶
URL은 자원(Resource)을 나타내고, HTTP 메서드가 행동을 나타냅니다.
GET /users → 사용자 목록 조회
GET /users/42 → ID 42번 사용자 조회
POST /users → 사용자 생성
PUT /users/42 → ID 42번 사용자 수정
DELETE /users/42 → ID 42번 사용자 삭제
URL에 동사를 쓰지 않습니다.
X /getUsers /createUser /deleteUser/42
O GET /users POST /users DELETE /users/42
API의 종류¶
| 종류 | 설명 | 예시 |
|---|---|---|
| 공개 API | 누구나 사용 가능 | 기상청 API, 공공데이터 포털 |
| 비공개 API | 내부에서만 사용 | 회사 내부 시스템 |
| 파트너 API | 허가된 파트너만 사용 | 결제 API (PG사) |
| 라이브러리 API | 코드 내에서 호출 | len(), requests.get() |
실습 미션¶
미션 1: 공개 API 탐색¶
아래 공개 API를 Python으로 호출하고 응답을 출력해보세요.
import requests
# 랜덤 고양이 사진 API
response = requests.get("https://api.thecatapi.com/v1/images/search")
data = response.json()
print("상태 코드:", response.status_code)
print("고양이 사진 URL:", data[0]["url"])
미션 2: JSONPlaceholder 활용¶
import requests
# 1. 게시글 목록 가져오기 (처음 5개만)
response = requests.get("https://jsonplaceholder.typicode.com/posts")
posts = response.json()
for post in posts[:5]:
print(f"[{post['id']}] {post['title']}")
# 2. 특정 게시글의 댓글 가져오기
post_id = 1
response = requests.get(f"https://jsonplaceholder.typicode.com/posts/{post_id}/comments")
comments = response.json()
print(f"\n게시글 {post_id}의 댓글 수: {len(comments)}")
미션 3: 상태 코드 확인¶
다양한 URL에 요청을 보내고 상태 코드를 확인해보세요.
import requests
urls = [
"https://jsonplaceholder.typicode.com/posts/1", # 존재하는 게시글
"https://jsonplaceholder.typicode.com/posts/9999", # 존재하지 않는 게시글
]
for url in urls:
response = requests.get(url)
print(f"{url}")
print(f" → 상태 코드: {response.status_code}")
print()
미션 4 (심화): 날씨 앱 만들기¶
OpenWeatherMap에서 무료 API Key를 발급받아, 도시 이름을 입력받아 현재 날씨를 출력하는 프로그램을 만드세요.
도시 이름을 입력하세요: Seoul
---
서울의 현재 날씨
기온: 22°C
날씨: 맑음
습도: 45%
핵심 요약¶
| 개념 | 설명 |
|---|---|
| API | 프로그램과 프로그램이 대화하는 규칙/접점 |
| HTTP API | HTTP 프로토콜 기반의 API (가장 일반적) |
| GET / POST | 데이터 조회 / 생성 요청 |
| 상태 코드 | 요청 결과 (200=성공, 404=없음, 500=서버오류) |
| JSON | API에서 데이터를 주고받는 표준 형식 |
| API Key | API 접근 권한을 증명하는 열쇠 |
| REST | URL=자원, HTTP메서드=행동으로 설계하는 방식 |
requests |
Python에서 HTTP 요청을 보내는 라이브러리 |