파이썬 requests 라이브러리로 웹 API 호출 시작하기: 기본 사용법과 예외 처리 요령

들어가며: 파이썬으로 웹 세상과 소통하는 첫걸음

토이리 블로그에 오신 것을 환영합니다. 이번 글에서는 파이썬 초보자도 쉽게 따라 할 수 있는 파이썬 requests 라이브러리 활용법을 다룹니다. 웹 개발을 하거나 데이터를 수집할 때, 외부 서버와 통신하여 필요한 정보를 가져오는 일은 매우 빈번하게 발생합니다. 브라우저 주소창에 주소를 입력하듯, 코드를 통해 웹 서버에 요청을 보내고 응답을 받아오는 과정을 이 글을 통해 확실하게 이해하실 수 있습니다.

[목차]

이 글을 끝까지 읽고 나시면 간단한 GET 요청을 보내 데이터를 가져오는 방법, 데이터를 전달하는 파라미터 구성 방식, 그리고 서버 통신 시 발생할 수 있는 오류를 안전하게 대처하는 예외 처리 요령까지 직접 실습해 보실 수 있습니다. 복잡한 이론보다는 실제 업무와 프로젝트에 바로 써먹을 수 있는 표준적인 패턴 위주로 설명해 드리겠습니다.

requests 라이브러리 설치와 기본 준비

파이썬의 기본 라이브러리만으로는 HTTP 통신을 구현할 때 코드가 다소 복잡해집니다. 파이썬 표준 라이브러리인 urllib 대신, 훨씬 직관적이고 다루기 쉬운 외부 패키지인 requests를 사용하는 것이 업계 표준입니다.

만약 아직 설치하지 않았다면, 터미널이나 명령 프롬프트에서 아래 명령어를 입력해 패키지를 설치해 주세요.

pip install requests

설정이 완료되었다면 스크립트 상단에 import requests를 선언하여 언제든 사용할 수 있습니다. 이제 가장 기본적인 GET 요청부터 차근차근 살펴보겠습니다.

가장 간단한 GET 요청 보내기

웹 서버에 정보를 요청할 때 가장 흔히 쓰는 방식이 바로 GET 방식입니다. 웹 페이지를 조회하거나 공개된 API 서버에서 데이터를 읽어올 때 사용합니다. 아래 코드는 공개된 테스트 API 서버에 요청을 보내고, 그 결과를 확인하는 가장 기본적인 형태입니다.

import requests

url = "https://api.github.com"
response = requests.get(url)

print(response.status_code)
print(response.text[:200])

코드를 실행하면 서버가 응답한 상태 코드(Status Code)와 응답 본문(Text)의 일부가 출력됩니다. 정상적인 통신이라면 상태 코드로 200이 반환됩니다.

응답 데이터 다루기: 텍스트와 JSON 형식

서버가 보내주는 응답 데이터는 대개 HTML 문서이거나 구조화된 JSON 데이터입니다. 최근의 대부분의 오픈 API는 JSON 형식으로 데이터를 교환하므로, 이를 파이썬의 딕셔너리 자료형으로 바로 변환해 주는 기능이 필수적입니다.

response.json() 메서드를 사용하면 JSON 문자열을 파이썬 객체로 손쉽게 바꿀 수 있습니다.

import requests

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

if response.status_code == 200:
    data = response.json()
    print("제목:", data.get("title"))
    print("완료 여부:", data.get("completed"))
else:
    print("데이터를 불러오지 못했습니다.")

이처럼 response.json()을 활용하면 키 값을 기준으로 원하는 데이터에 곧바로 접근할 수 있어 데이터 전처리나 자동화 스크립트 작성 시 매우 편리합니다.

쿼리 파라미터 전달과 헤더 설정 요령

서버에 검색어나 필터 조건을 전달해야 할 때는 주소 뒤에 물음표(?)를 붙여 직접 문자열을 조합하기보다, params 인자를 사용하는 것이 훨씬 안전하고 깔끔합니다. 특수문자 인코딩 등을 requests가 알아서 처리해 주기 때문입니다.

import requests

url = "https://httpbin.org/get"
params = {"search": "파이썬", "page": 1}
headers = {"User-Agent": "ToyLeeBlogBot/1.0"}

response = requests.get(url, params=params, headers=headers)
print(response.url)
print(response.json())

또한 headers 설정을 통해 브라우저인 것처럼 위장하거나, API 이용에 필요한 인증 토큰(Token)을 전달할 수 있습니다. 실무에서는 봇 차단을 방지하기 위해 User-Agent 헤더를 명시해 주는 것이 좋습니다.

초보자가 자주 하는 실수와 대처 요령

API 연동 작업을 처음 할 때 흔히 겪는 문제들과 이를 예방하는 요령을 정리했습니다.

상태 코드 확인 생략: 응답이 성공(200)했는지 확인하지 않고 곧바로 response.json()을 호출하여 JSONDecodeError가 발생하는 경우가 많습니다. 반드시 status_code나 raise_for_status()를 먼저 거쳐야 합니다.
타임아웃(Timeout) 설정 누락: 서버가 응답하지 않을 때 프로그램이 무한정 대기 상태에 빠질 수 있습니다. requests.get(url, timeout=5) 형태로 제한 시간을 반드시 걸어두어야 안정적인 시스템을 만들 수 있습니다.
인증 키나 비밀번호 하드코딩: 소스 코드 내부에 API 키를 그대로 적어두면 보안상 위험합니다. 환경 변수나 별도의 설정 파일로 분리하는 습관을 들여야 합니다.
예외 처리 부재: 네트워크 끊김이나 잘못된 URL 입력 등으로 발생하는 requests.exceptions.RequestException 예외를 잡지 않아 스크립트가 강제 종료되는 실수를 주의해야 합니다.

실무 적용을 위한 체크리스트

파이썬으로 API 연동 코드를 작성하고 배포하기 전에 아래 항목들을 차례대로 점검해 보세요.

[ ] 외부 패키지 설치 상태(pip list)를 확인했는가?
[ ] 요청 주소와 파라미터가 정확하게 전달되는지 테스트해 보았는가?
[ ] User-Agent나 필요한 인증 헤더가 올바르게 포함되었는가?
[ ] timeout 인자를 추가하여 무한 대기 상황을 방지했는가?
[ ] try-except 구문이나 raise_for_status()를 이용해 에러 처리를 구현했는가?
[ ] API 키나 민감한 정보가 소스 코드에 노출되지 않도록 안전하게 분리했는가?

마치며

이번 글에서는 파이썬 requests 라이브러리를 이용해 웹 API를 호출하고 응답 데이터를 다루는 기본적인 방법을 살펴보았습니다. 외부 서버와의 통신은 자동화 스크립트나 데이터 수집 프로그램의 핵심을 이루는 작업입니다. 오늘 다룬 표준적인 패턴과 예외 처리 요령을 바탕으로 본인의 프로젝트에 하나씩 적용해 보시길 바랍니다. 토이리 블로그에서는 앞으로도 실무에 바로 도움 되는 유용한 파이썬 팁과 개발 정보를 계속해서 공유해 드리겠습니다.

파이썬