파이썬 requests로 REST API 호출하는 법은? 초보자 실습방법은?

작성자:

매일 아침 30분씩 엑셀에 데이터를 복붙하던 노가다를 끝내다

직장인이라면 누구나 겪는 아침 출근 후 반복 작업 중 하나가 여러 사이트에서 데이터를 복사해 엑셀에 붙여넣는 일이었습니다. 저도 매일 30분씩 허비하는 시간이 너무 아까워서 파이썬으로 자동화를 시도해 보기로 마음먹었습니다. 하지만 ‘REST API’, ‘JSON 파싱’, ‘HTTP GET/POST’ 같은 용어들이 마치 외계어처럼 느껴졌고, IT 비전공자인 제게는 진입장벽이 너무나 높았죠. 공식 문서도 마치 외국어로 적힌 것처럼 내용이 머리에 들어오지 않았습니다.

그럼에도 불구하고 requests라는 파이썬 라이브러리를 접하고 나서는 상황이 조금 달라졌습니다. 이 라이브러리는 urllib보다 훨씬 간결하고 직관적이어서, 문서만 믿고 무작정 따라 하다 보니 어느새 10줄 남짓한 코드로 엑셀 데이터를 1초 만에 뽑아내는 단계에 도달했습니다. 물론 requests가 완벽한 도구는 아닙니다. 특히 대용량 요청이나 비동기 처리가 필요한 경우 속도 면에서 아쉬움을 느꼈고, 모바일 환경에서는 가끔 메뉴 인터페이스가 꼬여서 작업이 지연되는 불편함도 경험했습니다.

이 글에서는 저처럼 API라는 단어만 들어도 머리가 복잡해지는 초보자들이 흔히 겪는 난관을 조금이나마 덜어내기 위해, 제가 직접 시행착오를 겪으며 터득한 가장 쉽게 REST API를 호출하는 방법과 실습 과정을 공유하려고 합니다. 단순히 코드를 나열하는 데 그치지 않고, 초보자가 부딪힐 만한 함정과 그 해결책도 솔직하게 다루겠습니다.

목차

1. 코딩 초보의 API 자동화 테스트 환경

백엔드 서버를 직접 구축하거나 데이터베이스를 연결하는 복잡한 작업은 신경 쓰지 않았습니다. 제가 원하는 건 인터넷 브라우저가 하는 행동을 파이썬이 대신하게 만드는 가벼운 환경이었기 때문입니다. 안전하게 연습할 수 있는 환경을 갖추기 위해 저는 아래 세팅으로 테스트를 진행했습니다.

  • 운영체제 및 에디터: Windows 11 Pro, VS Code (Visual Studio Code)
  • 사용 언어: Python 3.12 (구버전도 어느 정도 호환되지만 최신 버전을 권장)
  • 사용 라이브러리: requests (파이썬 표준 라이브러리인 urllib보다 훨씬 직관적이고 코드가 간결합니다. 다만, 대량 요청 처리나 비동기에서는 한계가 있어 상황에 따라 다른 라이브러리도 고민해야 합니다.)
  • 테스트용 타겟 API: JSONPlaceholder (가입이나 인증 절차 없이 무료로 가상 게시판 데이터를 제공하는 개발자용 테스트 API 서버로, 초보자 연습용으로 적합합니다.)

2. 단계별 실습: 10줄 코드로 가상 서버 데이터 가져오기

파이썬 코드로 실제 데이터를 가져오는 과정을 시작해 보겠습니다. 인터넷 주소창에 URL을 입력하고 웹페이지 내용을 불러오는 행위를 ‘GET’ 요청이라고 합니다. 반대로 웹사이트에서 회원가입 양식을 작성해 서버에 정보를 보내는 작업을 ‘POST’ 요청이라고 부르죠. 이 두 가지 개념만 정확히 이해해도 API 호출의 기본은 잡힌 셈입니다.

1단계: requests 패키지 설치하기

VS Code 하단에 있는 터미널 창에 아래 명령어를 입력하면 requests 라이브러리를 설치합니다. 이미 설치된 상태라면 ‘Requirement already satisfied’라는 메시지가 뜹니다. 저는 이 부분에서 가끔 파이썬 환경이 꼬여서 설치가 제대로 안 되는 문제를 겪었는데, 그럴 때는 가상환경 재설정이 필요했습니다.

pip install requests

2단계: GET 요청으로 데이터 가져오기 (Read)

새 파일 api_test.py를 만들고, 아래 코드를 작성해 서버에서 1번 게시글 정보를 가져옵니다. 간단하지만 이 기본 구조가 REST API 통신의 핵심입니다. 다만 모바일 환경에서는 출력이 꼬이거나 콘솔 로그가 제대로 보이지 않아 한참을 들여다봐야 했던 기억이 있습니다.

import requests

1. 데이터를 요청할 API 주소 (엔드포인트)
url = "https://jsonplaceholder.typicode.com/posts/1"

2. GET 방식으로 데이터 요청하기
print("서버에 데이터를 요청하는 중입니다...")
response = requests.get(url)

3. 서버의 응답 상태 확인 (200이면 정상)
if response.status_code == 200:
    print("✅ 통신 성공!")

    # 4. JSON 형태의 응답 데이터를 파이썬 딕셔너리로 변환
    data = response.json()

    print("--- [수신된 데이터] ---")
    print(f"제목: {data['title']}")
    print(f"내용: {data['body']}")
else:
    print(f"❌ 통신 실패: 에러 코드 {response.status_code}")

이 코드를 돌리면, 상태 코드 200이 나와야 제대로 된 응답이라는 걸 알 수 있습니다. 그런데 저는 종종 403 같은 권한 에러나 500 서버 오류를 보면서 API가 항상 믿을 만한 건 아니라는 점을 체감했습니다. 아까운 시간 낭비를 줄이려면 상태 코드를 꼼꼼히 확인하는 습관이 필수입니다.

3단계: POST 요청으로 새로운 데이터 전송하기 (Create)

이번에는 데이터를 서버로 전송하는 방법입니다. GET과는 달리 보낼 내용이 필요한데, 이를 payload라고 부릅니다. 제 경험상 여기서 JSON 형식이 맞지 않거나 키 이름이 틀리면 아무리 시도해도 400대 에러가 뜨니, 딕셔너리 구조를 정확히 맞추는 게 중요합니다.

import requests

url = "https://jsonplaceholder.typicode.com/posts"

서버로 보낼 나의 데이터 세팅
my_data = {
    "title": "파이썬 자동화 테스트",
    "body": "이것은 requests 모듈을 이용한 POST 요청 테스트입니다.",
    "userId": 999
}

POST 방식으로 데이터 전송하기
response = requests.post(url, json=my_data)

if response.status_code == 201: # POST 성공 시 보통 201(Created) 코드가 반환됩니다.
    print("✅ 데이터 전송 성공!")
    print("서버 응답 결과:", response.json())

실제로 저도 POST 요청을 처음 할 때는 응답이 201이 안 뜨고 400이나 404가 뜨면서 데이터를 못 보냈습니다. 서버가 요구하는 정확한 키와 값, 그리고 헤더 설정이 얼마나 중요한지 뼈저리게 느꼈죠. 또, JSONPlaceholder 같은 테스트용 API가 아닌 실제 서버에서는 인증 문제로 에러가 더 빈번합니다. 그래서 실전에서 바로 쓰려면 인증 토큰이나 세션 관리도 반드시 챙겨야 합니다.

💡 여기서 주의할 점: User-Agent와 Timeout 설정의 중요성

실제 네이버나 공공 데이터 API를 호출할 때, 아무 옵션 없이 requests.get()만 보내면 서버가 “이건 봇이네”라며 403 에러를 내뱉는 경우가 많았습니다. 단순히 요청만 하면 차단당하는 상황이 꽤 자주 있었죠. 그래서 저는 헤더에 ‘User-Agent’ 값을 넣어 크롬 브라우저에서 접속한 것처럼 속이는 방식을 꼭 씁니다. 이게 없으면 서버가 자동화된 요청으로 인식하고 무조건 막아버리더군요.

그리고 서버가 응답을 안 할 때 파이썬 프로그램이 무한 대기하는 문제도 심각했습니다. 기본적으로 requests는 타임아웃 설정이 없어서, 서버가 멈추거나 늦게 응답하면 꼼짝 못 합니다. 그래서 저는 꼭 timeout=5 (5초 한도)를 넣는 습관을 들였는데, 이게 없으면 프로그램이 멈춰서 한참 낭패를 봅니다.

3. 내가 직접 겪은 뼈아픈 에러 2가지와 완벽 탈출구

튜토리얼 코드들은 보통 잘 돌아가지만, 실무 환경의 API 통신에서는 예상 밖 에러가 한두 번이 아니었습니다. 특히 두 가지 에러 때문에 시간과 정신을 많이 까먹었는데, 이걸 공유하지 않으면 후배들이 저랑 똑같이 고생할 것 같아 적습니다.

첫 번째 참사: JSONDecodeError – JSON으로 착각한 HTML 응답

공공 데이터 API를 호출한 뒤 평소처럼 data = response.json()을 썼는데, 갑자기 에러가 터졌습니다. API 문서에는 JSON 반환이 명시돼 있었는데, 서버에서 500 상태 코드와 함께 ‘서버 점검 중’이라는 HTML 페이지를 보내 온 겁니다. 파이썬이 HTML을 JSON으로 해석하려 하니 당연히 오류가 났죠. 그 뒤로 저는 무조건 if response.status_code == 200: 조건을 확인하고, 그래도 의심스러우면 response.text를 출력해 실제 응답 내용을 눈으로 직접 확인합니다. 이걸 안 하면 문제 원인을 잡기도 전에 코드가 멈춰서 낭패를 봅니다.

두 번째 위기: 무한 대기(Hanging) 현상으로 프로그램 멈춤

한 번은 API 호출 봇을 서버에 올리고 퇴근했는데, 다음 날 출근해 보니 프로그램이 첫 줄에서 멈춰 있었습니다. 에러 메시지도 없었고, 그냥 멍하니 멈춘 상태였죠. 원인은 타겟 서버가 너무 느려서 응답을 안 한 건데, requests가 기본적으로 타임아웃 제한 없이 기다려서 발생한 일이었습니다. 이 상태에서 아무리 시간이 지나도 복구가 안 됐죠. 결국 저는 requests.get(url, timeout=10)처럼 타임아웃을 명시하고, try-except 문으로 예외를 처리하는 방식으로 문제를 해결했습니다. 이 설정 없이는 언제 또 멈출지 몰라서 마음이 편하지 않습니다.

4. 파이썬 자동화 도입 후 체감한 놀라운 업무 시간 단축

저는 requests 모듈만 제대로 다뤄도 업무 효율이 이렇게 바뀔 줄 몰랐습니다. 매일 아침 직접 웹사이트에서 환율과 주가 정보를 복사해서 엑셀에 붙여넣던 작업이 약 30분 걸렸는데, 이제는 단 1.5초 만에 끝납니다. 버튼 클릭 한 번에 이렇게 빠른 결과가 나온다는 게 아직도 신기할 정도입니다.

다만 모바일 환경에서는 API 호출 결과를 처리하는 과정에서 메뉴가 꼬여서 작업 흐름이 자주 끊겼습니다. 이 부분은 코드보다는 UI 설계 문제라서 좀 더 고쳐야 할 것 같습니다. 그리고 JSON 데이터를 판다스(Pandas)로 바로 엑셀에 넣으면서 휴먼 에러가 거의 사라진 건 분명하지만, 처음에는 헤더 설정이나 타임아웃 옵션을 빼먹어 프로그램이 죽는 일이 종종 있었습니다. 이 점을 놓치면 프로그램이 멈춰서 다시 실행하는 데 시간을 허비하기 쉽습니다.

  • 시간의 압축: 반복하던 30분짜리 수작업이 스크립트 실행 1.5초 만에 끝납니다.
  • 휴먼 에러 제로: API에서 받은 JSON 데이터를 판다스에 넣어 엑셀로 변환해, 오타나 누락이 거의 없었습니다.
  • 업무 확장성: API 원리를 이해하고 나서 슬랙 API를 이용해 조건별 알림 봇까지 직접 만들었는데, 이 과정이 생각보다 쉽지는 않았습니다. 특히 인증 토큰 처리와 비동기 알림 설정 부분에서 시간을 많이 썼습니다.

5. 3줄 요약 및 이런 분들께 강력 추천합니다

오늘 소개한 REST API 호출 방법을 정리하면 다음과 같습니다.

  1. 파이썬에서 requests 라이브러리를 설치(pip install requests)하면 API 요청을 시작할 수 있습니다.
  2. 데이터를 가져올 땐 GET, 보낼 땐 POST 방식을 쓰고, 응답은 .json() 메서드로 쉽게 다룹니다.
  3. 실무에서는 Headers(User-Agent)와 Timeout 옵션을 꼭 넣어야 네트워크 문제나 서버 차단으로부터 프로그램을 보호할 수 있습니다.

제가 이 방법을 추천하는 건, 매일 비슷한 데이터 수집 업무에 지쳐 있거나, 마케팅 데이터 통합에 골머리를 앓는 분, 또는 ChatGPT 같은 AI API 연동을 시도하려는 입문자분들입니다. 다만, 단순히 화면을 녹화하거나 클릭을 자동화하는 작업에는 이 방법이 적합하지 않습니다. 그런 경우에는 셀레니움(Selenium) 같은 도구가 더 맞을 수 있습니다.