Python으로 API 호출하기: requests 사용법

API 호출의 기본 원리

API(Application Programming Interface)는 프로그램끼리 정해진 규칙에 따라 데이터를 주고받는 창구입니다. 웹 API는 주로 HTTP 프로토콜을 사용하며, 클라이언트가 URL로 요청을 보내면 서버가 응답을 반환합니다. Python 프로그램에서 API를 호출할 때는 요청 방식, URL, 전달할 데이터, 응답 형식을 구분해서 이해하는 것이 중요합니다.

대표적인 HTTP 메서드로는 데이터를 조회하는 GET, 새 데이터를 전달하거나 생성하는 POST가 있습니다. 서버 응답은 JSON 형식인 경우가 많습니다. JSON은 키와 값으로 구성된 텍스트 형식이며, Python에서는 딕셔너리나 리스트로 쉽게 변환해 사용할 수 있습니다.

requests 설치와 첫 요청

Python에서 HTTP 요청을 가장 간편하게 다룰 수 있는 라이브러리 중 하나가 requests입니다. 터미널에서 다음 명령으로 설치합니다.

pip install requests

설치 후에는 import requests로 불러올 수 있습니다. 아래 예시는 공개 테스트 API에 GET 요청을 보내 응답 내용을 확인하는 코드입니다.

import requests

url = "https://jsonplaceholder.typicode.com/posts/1"
response = requests.get(url)

print(response.status_code)
print(response.json())

requests.get()은 지정한 URL에 GET 요청을 보냅니다. response에는 서버의 응답이 담기며, status_code는 HTTP 상태 코드입니다. 일반적으로 200은 요청 성공을 의미합니다. response.json()은 JSON 응답을 Python 객체로 변환합니다.

쿼리 파라미터로 조건 전달하기

조회 조건은 URL 뒤에 직접 붙일 수도 있지만, params 인자를 사용하면 더 안전하고 읽기 쉬운 코드를 작성할 수 있습니다. 예를 들어 게시글 목록에서 userId가 1인 데이터만 요청하는 방식입니다.

import requests

url = "https://jsonplaceholder.typicode.com/posts"
params = {"userId": 1}
response = requests.get(url, params=params, timeout=10)

posts = response.json()
print(posts[0]["title"])

params에 딕셔너리를 전달하면 requests가 이를 URL 쿼리 문자열로 변환합니다. timeout은 서버 응답이 지나치게 오래 걸릴 때 프로그램이 계속 기다리지 않도록 제한 시간을 설정하는 옵션입니다. 실무 코드에서는 timeout을 지정하는 습관이 필요합니다.

POST 요청으로 JSON 데이터 보내기

POST 요청은 서버에 새로운 데이터를 전달할 때 사용합니다. API 문서에서 JSON 본문을 요구한다면 json 인자에 딕셔너리를 전달합니다.

import requests

url = "https://jsonplaceholder.typicode.com/posts"
data = {
"title": "Python API 실습",
"body": "requests로 POST 요청 보내기",
"userId": 1
}

response = requests.post(url, json=data, timeout=10)
response.raise_for_status()
print(response.json())

json=data를 사용하면 requests가 JSON 변환과 Content-Type 헤더 설정을 처리합니다. form 형식 데이터를 요구하는 API라면 json 대신 data 인자를 사용해야 하므로, 항상 API 문서의 요청 형식을 확인해야 합니다.

응답과 오류를 안전하게 처리하는 방법

API 호출이 항상 성공하는 것은 아닙니다. URL이 잘못되었거나, 인증 정보가 없거나, 서버에 문제가 생길 수 있습니다. response.raise_for_status()는 400번대 또는 500번대 상태 코드일 때 예외를 발생시켜 실패를 놓치지 않게 합니다. 네트워크 오류까지 처리하려면 try-except를 사용합니다.

import requests

try:
response = requests.get("https://api.example.com/data", timeout=10)
response.raise_for_status()
result = response.json()
except requests.exceptions.Timeout:
print("요청 시간이 초과되었습니다.")
except requests.exceptions.RequestException as error:
print(f"API 호출 중 오류가 발생했습니다: {error}")

JSON 응답이 아닐 가능성도 있으므로, 외부 API를 다룰 때는 상태 코드와 응답 본문을 함께 점검하는 것이 좋습니다. 특히 API 키, 토큰, 비밀번호 같은 민감한 값은 코드에 직접 작성하지 말고 환경 변수로 관리해야 합니다.

효율적인 학습방법

API 학습의 기초는 작은 요청을 직접 보내고 응답을 관찰하는 것입니다. 먼저 공개 테스트 API로 GET 요청을 실행해 상태 코드와 JSON 구조를 확인해 보세요. 다음에는 params를 이용해 조건을 전달하고, POST 요청으로 데이터를 보내는 순서로 연습하면 원리를 자연스럽게 익힐 수 있습니다.

새 API를 사용할 때는 코드부터 작성하기보다 문서를 먼저 읽어야 합니다. 엔드포인트 URL, HTTP 메서드, 필요한 헤더와 인증 방식, 요청 데이터 형식, 성공·실패 응답 예시를 확인하면 대부분의 문제를 빠르게 해결할 수 있습니다. requests는 호출 도구이고, 실제 API 사용의 핵심은 서버가 정한 규칙을 정확히 이해하는 데 있습니다.

자주 묻는 질문