Python Requests로 API 호출, 감으로 끝내지 말고 제대로 이해해보자
처음 API를 접했을 때를 떠올려보면… 솔직히 말해서 머리가 좀 복잡해집니다. URL이니 endpoint니, status code에 GET·POST·PATCH까지. 하나하나 보면 아는 단어 같은데, 막상 연결하려니 손이 멈추죠. 저도 그랬습니다. 노트북 앞에 앉아 커피는 식어가고, 공식 문서는 열려 있는데 집중은 안 되고요.
그래서 이 글은 번역체 설명이 아니라, 한국 개발자가 자연스럽게 이해할 수 있는 흐름으로 정리했습니다. 목표는 단순합니다. Python Requests 모듈로 API 요청을 보내고, 응답을 안정적으로 처리하는 핵심을 짧은 시간 안에 체득하는 것. 15분이면 충분합니다.
“API는 어렵다기보다, 아직 익숙하지 않을 뿐이다.”
왜 굳이 Requests 모듈일까?
Python으로 HTTP 요청을 보낼 수 있는 방법은 여럿 있지만, 실무에서 가장 자주 만나게 되는 건 단연 requests입니다. 이유는 단순해요. 읽기 쉽고, 쓰기 편하고, 의도가 바로 보입니다.
코드를 보면 마치 이렇게 말하는 느낌이죠.
“이 URL로 GET 요청 하나 보낼게.”
설치는 아주 간단합니다.
pip install requests
가능하면 가상 환경에서 설치하세요. 요즘은 uv 같은 툴도 많이 씁니다. 프로젝트가 조금만 커져도 의존성 관리가 얼마나 중요한지 바로 체감하게 됩니다. (이건 진짜 경험에서 나오는 이야기예요.)
URL과 endpoint, 너무 어렵게 생각하지 말자
URL은 그냥 주소입니다. 집 주소랑 크게 다르지 않아요.
- Domain: techwithtim.net → 동네 이름
- Path: /courses/python → 그 동네 안의 특정 장소
- Query parameter: ?page=2&sort=latest → “2페이지로 보여주고, 최신순으로 정렬해줘”라는 추가 요청
Query parameter는 ? 뒤에 붙고, 서버에게 조건을 더 전달할 때 사용합니다. 페이지네이션, 필터링, 검색—이런 것들 전부 여기서 처리돼요.
Request와 Response 구조, 대화라고 생각하면 편하다
API 통신은 결국 클라이언트와 서버의 대화입니다.
- 클라이언트: “이 데이터 필요해요.”
- 서버(API): “오케이. 대신 규칙은 지켜줘.”
Request에는 뭐가 들어갈까?
- Method: GET, POST, PUT, PATCH, DELETE
- Path: /api/post
- Headers: Authorization token 같은 메타데이터
- Body: 서버로 보내는 실제 데이터
Response는?
- Status code: 요청 결과 요약
- Body: 요청한 데이터(JSON이 대부분)
- Headers: 서버 정보, 캐시 정책 등
예를 들어 게시글을 수정하는 PATCH 요청을 보낸다고 해볼게요. 새로운 title과 description을 body에 담고, Authorization token을 headers에 포함합니다. 성공하면 보통 200이나 204 status code가 돌아옵니다. 이때 묘하게 안도감이 들죠.
HTTP status code, 서버의 표정 읽기
Status code는 서버의 반응을 아주 솔직하게 보여줍니다.
- 200 OK: 문제 없음
- 201 Created: 새 리소스 생성 완료
- 404 Not Found: 요청한 리소스가 없음
- 403 Forbidden: 권한 부족
- 500 Server Error: 서버 내부 문제
에러 메시지보다 status code를 먼저 보는 습관을 들이면, 디버깅 속도가 훨씬 빨라집니다.
HTTP method 한 번에 정리
- GET: 데이터 조회
- POST: 데이터 생성
- PUT: 전체 업데이트
- PATCH: 부분 업데이트
- DELETE: 삭제
요청의 목적을 method로 명확히 드러내는 게 REST API의 기본 철학입니다.
Requests로 GET 요청 보내보기
import requests
response = requests.get("https://api.example.com/posts")
print(response.status_code)
print(response.headers)
print(response.json())
response.json()은 정말 자주 쓰입니다. JSON 응답을 바로 Python dict로 바꿔주니까요.
Query parameter 추가하기
params = {
"page": 2,
"limit": 10
}
response = requests.get(URL, params=params)
직접 URL 문자열을 조합할 필요 없이, Requests가 알아서 처리해줍니다. 이런 부분에서 생산성이 확 올라가죠.
POST 요청으로 데이터 보내기
payload = {
"title": "New Post",
"description": "Hello API"
}
response = requests.post(URL, json=payload)
json= 옵션을 쓰면 Content-Type: application/json header까지 자동으로 설정됩니다. 사소하지만 정말 편한 기능이에요.
에러 처리와 timeout, 안정적인 코드의 핵심
API 호출은 언제든 실패할 수 있습니다. 그래서 예외 처리는 선택이 아니라 필수예요.
from requests.exceptions import Timeout, RequestException
try:
response = requests.get(URL, timeout=5)
response.raise_for_status()
except Timeout:
print("요청 시간이 너무 오래 걸립니다.")
except RequestException as e:
print(f"요청 실패: {e}")
- timeout: 무한 대기 방지
- raise_for_status(): 4xx, 5xx status code를 예외로 처리
이걸 안 넣으면, 어느 날 프로그램이 조용히 멈춰 있는 상황을 마주할 수도 있습니다.
Authorization token, ‘당신 누구세요?’에 대한 답
대부분의 API는 인증을 요구합니다. 즉, “누가 요청했는지”를 확인하죠.
headers = {
"Authorization": "Bearer YOUR_TOKEN"
}
response = requests.get(URL, headers=headers)
이 token 덕분에 내 계정 정보, 개인 데이터, 제한된 기능에 접근할 수 있습니다. 없으면 보통 401이나 403이 바로 돌아옵니다.
Brilliant로 학습하면 뭐가 다를까?
글로 읽는 게 잘 맞는 사람이 있는 반면, 직접 손으로 만져봐야 이해되는 사람도 있습니다. Brilliant는 후자에게 잘 맞는 플랫폼이에요.
짧은 대화형 강의로 구성돼 있고, MIT·Caltech·Google 출신 전문가들이 만든 콘텐츠라 완성도가 높습니다. 출퇴근길에 잠깐씩 풀어보기도 좋고요.
👉 brilliant.org/techwithtim
- 무료로 시작 가능
- 연간 Premium 구독 시 20% 할인
- Python, CS, Data, AI까지 폭넓게 제공
자주 나오는 질문 정리 (FAQ)
Q1. Requests는 async인가요?
A. 아닙니다. 기본은 synchronous입니다. async가 필요하면 aiohttp를 참고하세요.
Q2. GET 요청에 body를 넣어도 되나요?
A. 기술적으로 가능하지만 일반적으로 권장되지는 않습니다.
Q3. timeout은 꼭 설정해야 하나요?
A. 네, 실무에서는 거의 필수입니다.
Q4. raise_for_status()는 언제 쓰나요?
A. 대부분의 경우 항상 사용하는 게 좋습니다.
Q5. Authorization token은 어디에 보관하나요?
A. 환경 변수(.env) 사용을 추천합니다.
Q6. PUT과 PATCH의 차이는 뭔가요?
A. PUT은 전체, PATCH는 일부만 업데이트합니다.
Q7. JSON 말고 다른 format도 쓰이나요?
A. 가능하지만, 요즘은 JSON이 사실상 표준입니다.
Q8. status code를 다 외워야 하나요?
A. 자주 쓰는 것만 익숙해지면 충분합니다.
Q9. Requests는 2025년에도 유효한가요?
A. 네. 여전히 가장 널리 쓰이는 라이브러리 중 하나입니다.
마치며
API는 결국 규칙이 있는 대화입니다. 요청을 명확히 보내고, 응답을 차분히 해석하면 생각보다 어렵지 않습니다.
처음엔 낯설고 느릴 수 있어요. 하지만 어느 순간 로그를 보면서 이런 생각이 들 겁니다.
“아, 이제 이 흐름이 보이네.”
이 글이 그 지점까지 가는 데 작은 도움이 되길 바랍니다.