파이썬 requests 기본 API 가이드 r.get params r.post put patch delete head options 의미 차이

파이썬 requests 기본 API 가이드 r.get params r.post put patch delete head options 의미 차이

🚀 한 번에 정리하는 HTTP 메서드 사용법과 실전 요청 패턴

HTTP 요청을 다루다 보면 같은 URL도 메서드에 따라 결과가 달라지고, 파라미터를 어디에 넣느냐에 따라 서버가 완전히 다른 의미로 해석하곤 합니다.
requests는 이 복잡함을 간결한 함수로 풀어주지만, r.get과 r.post, 그리고 put, patch, delete, head, options의 의미적 차이를 정확히 이해하지 못하면 디버깅 시간만 길어지기 쉽죠.
실무에서 헷갈리기 쉬운 쿼리스트링과 본문, 멱등성 개념, 응답 객체 활용까지 핵심을 압축해서 정리해 드립니다.
차근차근 따라오면 API 문서를 읽을 때도 훨씬 자신감이 붙을 거예요.

이 글은 파이썬 requests 기본 API를 중심으로, r.get의 params 사용법과 r.post 및 put, patch, delete, head, options 메서드의 의미적 차이를 분명하게 설명합니다.
각 메서드가 표준 HTTP에서 어떤 의도를 갖는지, 실제 요청을 만들 때 어떤 필드를 선택해야 하는지, 그리고 응답 r 객체를 어떻게 점검하고 예외를 다뤄야 하는지까지 자연스럽게 연결해 설명합니다.
불필요한 이론보다 실전에서 바로 써먹을 수 있는 문장과 예제로 채워, 초보자도 쉽고 빠르게 습득할 수 있도록 구성했습니다.

🔗 requests 기본 API와 응답 객체 r 개요

파이썬에서 HTTP를 가장 간단하게 다루는 방법 중 하나가 requests 라이브러리입니다.
핵심은 URL과 메서드의 결합, 그리고 결과를 담는 응답 객체 r 입니다.
r 은 서버가 보낸 상태 코드와 헤더, 본문을 안전하게 다루도록 돕고, 디버깅과 로깅에도 바로 쓰일 수 있습니다.
이 섹션에서는 기본 호출 형태와 r 이 제공하는 주요 속성, 성공 기준을 판단하는 패턴을 한 눈에 정리합니다.

요청은 크게 r.get url params, r.post, r.put, r.patch, r.delete, r.head, r.options 같은 메서드로 보냅니다.
각 메서드는 서버에 전달하는 의미가 다르지만, 공통적으로 반환값은 Response 타입의 r 로 통일되어 있습니다.
즉, 어떤 메서드를 쓰더라도 r.status_code, r.headers, r.text, r.json 같은 동일한 접근 방식으로 결과를 확인할 수 있습니다.
이 일관성이 requests 를 실무 친화적으로 만드는 가장 큰 이유입니다.

import requests

# 1) 가장 기본적인 GET 호출: 쿼리는 params 로
r = requests.get("https://api.example.com/search", params={"q": "python", "page": 1})

# 2) 공통적으로 확인하는 응답 정보
print(r.status_code)      # 200, 404 등 상태 코드
print(r.url)              # 인코딩된 최종 요청 URL (쿼리 포함)
print(r.headers.get("Content-Type"))  # 응답 콘텐츠 유형
print(r.text[:120])       # 문자열 본문 미리보기
print(r.json())           # JSON 본문을 파싱 (JSON 아닐 경우 예외)

# 3) 에러 핸들링 패턴
try:
    r.raise_for_status()  # 4xx/5xx 면 HTTPError 발생
except requests.HTTPError as e:
    print("요청 실패:", e)

• 🔎GET 요청의 쿼리는 params= 로 넣고, 최종 URL 은 r.url 로 검증합니다.
• 🧭성공 판단은 r.ok 또는 r.raise_for_status() 로 표준화합니다.
• 🧱JSON 응답만 신뢰할 때는 r.headers[‘Content-Type’] 를 점검합니다.

🛠️ r.get url params 사용법과 쿼리스트링 처리

r.get() 메서드는 가장 기본적인 HTTP 요청 방식인 GET을 수행합니다.
GET은 주로 서버로부터 데이터를 조회(read)할 때 사용되며, 데이터를 요청하는 매개변수는 params= 인자에 사전 형태로 전달합니다.
이 인자는 자동으로 쿼리스트링으로 변환되어 URL 끝에 붙으며, requests가 내부적으로 올바르게 인코딩해주기 때문에 별도의 수작업이 필요 없습니다.

예를 들어, 검색 API에서 “python”이라는 키워드와 “page=1”을 함께 전송하려면 다음처럼 작성합니다.
이때 r.url을 출력하면 최종적으로 전송된 URL 전체를 확인할 수 있어, 파라미터 인코딩 오류나 공백 문제를 쉽게 점검할 수 있습니다.

import requests

params = {"q": "python requests", "page": 1, "sort": "recent"}
r = requests.get("https://api.example.com/search", params=params)

print(r.url)
# 결과 예시:
# https://api.example.com/search?q=python+requests&page=1&sort=recent

만약 직접 URL 뒤에 쿼리를 붙이는 경우 requests는 이중 인코딩을 피하기 위해 적절히 병합합니다.
단, params와 URL 내 쿼리를 함께 지정할 경우 중복 키가 발생하면 params의 값이 우선 적용됩니다.
이는 명시적인 인자가 더 높은 우선순위를 갖는 requests의 표준 동작입니다.

💬 GET은 데이터를 변경하지 않는 ‘조회 전용’ 요청으로 간주됩니다.
따라서 요청 본문(body)을 포함하지 않으며, 동일한 요청을 여러 번 보내도 서버의 상태가 변하지 않습니다.

• 📎params= 인자는 자동 URL 인코딩을 수행하므로 수동으로 urllib.parse를 사용할 필요가 없습니다.
• 🌐서버 로그에 노출될 수 있으므로 민감한 데이터(API 키, 비밀번호 등)는 GET 대신 POST로 전송하세요.
• 🧭결과 캐싱을 허용하려면 HTTP 헤더에 Cache-Control을 설정해 서버와 협의해야 합니다.

⚙️ r.post put patch 의미 차이와 본문 전송 방식

HTTP는 단순히 데이터를 요청하거나 받는 프로토콜이 아니라, 서버 자원의 생성·수정·삭제 등 상태 변화를 의미적으로 표현하는 규약을 가지고 있습니다.
requests 라이브러리에서 r.post, r.put, r.patch 는 이러한 의도를 그대로 반영하며, 각 메서드는 목적에 따라 전송 위치와 내용이 다르게 처리됩니다.

r.post()는 새로운 자원을 생성하거나, 서버에 데이터를 제출(submit)할 때 사용합니다.
전송 데이터는 보통 data= 또는 json= 인자에 담아 본문(body)으로 전송합니다.
이때 headers에 Content-Type: application/json 이 자동 지정되어 JSON 직렬화를 수행하므로, 별도 인코딩 과정이 필요 없습니다.

import requests

payload = {"title": "새 게시물", "content": "본문 내용입니다."}
r = requests.post("https://api.example.com/posts", json=payload)

print(r.status_code)
print(r.json())

r.put()은 이미 존재하는 자원을 “전체 교체”할 때 사용합니다.
즉, 동일한 엔드포인트에 새로운 데이터를 보내면 기존 자원을 완전히 덮어씌웁니다.
반면 r.patch()는 일부 필드만 부분적으로 수정할 때 사용됩니다.
이 둘은 실무에서 종종 혼용되지만, REST 표준에서는 put이 멱등(idempotent)해야 한다는 점이 중요합니다.
즉, 동일한 요청을 여러 번 보내도 결과가 같아야 합니다.

requests에서 data=를 사용할 때는 application/x-www-form-urlencoded 형태로 인코딩됩니다.
이는 웹 폼 전송 방식과 같으며, JSON API가 아닌 서버에 주로 사용됩니다.
반면 json=을 쓰면 requests가 자동으로 직렬화하여 JSON 헤더를 추가합니다.

🔍 r.delete head options 활용 시점과 주의사항

HTTP 표준에는 POST, PUT, PATCH 외에도 서버의 자원을 제어하거나 메타정보를 확인하기 위한 다양한 메서드가 정의되어 있습니다.
requests 라이브러리에서도 이들을 동일한 형식으로 제공합니다.
그중 대표적인 것이 r.delete(), r.head(), r.options()입니다.
이 세 가지는 주로 RESTful API 설계에서 특정 상황에만 호출되며, 잘못 사용하면 의도치 않은 데이터 손실을 초래할 수 있으므로 정확한 의미를 이해해야 합니다.

🗑️ r.delete() – 자원 삭제 요청

r.delete()는 서버에 존재하는 특정 자원을 삭제하도록 요청합니다.
URL에 자원의 고유 식별자(ID)를 포함하여 호출하며, 성공 시 보통 HTTP 204 No Content나 200 OK를 반환합니다.
이 요청은 실제 데이터를 제거하므로 반드시 사용자 인증, 권한 검증이 선행되어야 합니다.

r = requests.delete("https://api.example.com/posts/101")
print(r.status_code)  # 204 or 200 expected

📄 r.head() – 응답 본문 없이 헤더만 요청

r.head()는 GET 요청과 유사하지만, 본문을 제외한 헤더만 반환합니다.
이 메서드는 리소스 존재 여부 확인, 파일 크기(Content-Length) 확인, 수정 시점(Last-Modified) 파악 등에 자주 쓰입니다.
응답 본문을 받지 않기 때문에 트래픽 절약과 속도 면에서 매우 효율적입니다.

r = requests.head("https://api.example.com/files/report.pdf")
print(r.headers["Content-Length"])
print(r.headers.get("Last-Modified"))

🧩 r.options() – 서버가 허용하는 메서드 확인

r.options()는 서버가 특정 URL에 대해 지원하는 HTTP 메서드를 조회하는 요청입니다.
특히 CORS(교차 출처 요청) 환경에서 브라우저가 자동으로 보내는 preflight 요청이 바로 OPTIONS입니다.
이 응답의 Allow 헤더를 보면 해당 자원이 수용 가능한 메서드를 한눈에 알 수 있습니다.

r = requests.options("https://api.example.com/posts")
print(r.headers.get("Allow"))
# 예시 응답: GET, POST, OPTIONS

• 🧭DELETE 호출 전, r.options() 로 메서드 허용 여부를 먼저 확인하세요.
• 📡파일 유무 확인 시 HEAD는 GET보다 효율적이며, 다운로드 시간을 단축합니다.
• ⚙️OPTIONS 응답의 Allow 헤더는 서버의 API 정책을 빠르게 점검할 때 유용합니다.

💡 멱등성 캐싱 리다이렉트 타임아웃 예외 처리 요령

requests를 사용할 때는 단순히 요청을 보내는 것뿐 아니라, 각 HTTP 메서드의 멱등성(idempotency), 캐싱, 리다이렉트, 예외 처리 개념을 함께 이해하는 것이 중요합니다.
이 네 가지는 API의 신뢰성과 성능, 그리고 안전성을 결정짓는 핵심 포인트입니다.

🔁 멱등성과 안전성의 차이

멱등성은 같은 요청을 여러 번 반복해도 결과가 변하지 않는 성질을 말합니다.
예를 들어 GET, PUT, DELETE는 멱등하지만, POST는 요청할 때마다 새로운 결과(예: 데이터 추가)를 생성하기 때문에 멱등하지 않습니다.
이 개념을 이해하면 API 호출 실패 시 재시도 로직을 안정적으로 구성할 수 있습니다.

💬 GET·PUT·DELETE는 멱등성이 있고, POST는 그렇지 않다 — 이 한 문장으로 대부분의 요청 전략을 세울 수 있습니다.

📦 캐싱과 리다이렉트의 처리

GET 요청은 서버나 클라이언트에서 캐싱이 가능하며, 응답 헤더의 Cache-Control, ETag 값을 기반으로 캐시 정책을 조정할 수 있습니다.
requests는 자동으로 30x 리다이렉트를 따라가며, r.history 속성에 리다이렉트 경로가 기록됩니다.
필요 시 allow_redirects=False 옵션으로 이를 차단할 수도 있습니다.

r = requests.get("https://example.com/redirect", allow_redirects=True)
print(r.url)         # 최종 목적지 URL
print(r.history)     # 리다이렉트 경로 목록

⏱️ 타임아웃과 예외 처리

네트워크 오류나 서버 지연이 발생했을 때 프로그램이 멈추지 않도록, timeout 옵션은 필수입니다.
예외는 requests.exceptions 모듈에서 제공하며, 연결 실패(ConnectionError), 타임아웃(Timeout), HTTPError 등을 개별적으로 처리할 수 있습니다.

import requests

try:
    r = requests.get("https://api.example.com/data", timeout=5)
    r.raise_for_status()
except requests.exceptions.Timeout:
    print("요청 시간이 초과되었습니다.")
except requests.exceptions.ConnectionError:
    print("서버에 연결할 수 없습니다.")
except requests.exceptions.HTTPError as e:
    print("HTTP 오류 발생:", e)

• 🔁멱등성 있는 요청(GET·PUT)은 안전하게 재시도할 수 있습니다.
• 🧭Cache-Control 과 ETag 를 활용하면 반복 요청의 트래픽을 줄일 수 있습니다.
• ⏱️timeout 은 requests의 안정성을 높이는 필수 매개변수입니다.

❓ 자주 묻는 질문 FAQ

🧠 HTTP 메서드 이해와 requests 활용 정리

파이썬 requests는 HTTP 통신을 가장 단순하고 직관적으로 다룰 수 있는 라이브러리입니다.
r.get, r.post, r.put, r.patch, r.delete, r.head, r.options 등 각 메서드는 서로 다른 의미적 목적을 가지고 있으며, RESTful API 설계 원칙에 따라 적절히 구분해 사용해야 합니다.
특히 GET과 POST의 차이, PUT과 PATCH의 멱등성 개념, DELETE의 안전한 사용, HEAD/OPTIONS의 진단적 활용을 이해하면 API 통신을 더욱 안정적으로 구현할 수 있습니다.

실무에서는 params, data, json 인자 구분과 timeout 설정, raise_for_status()를 통한 예외 관리가 필수적입니다.
또한 r 객체의 속성(status_code, headers, text, json())을 잘 활용하면 응답 상태를 한눈에 파악할 수 있고, 세션(Session)으로 반복 요청의 효율을 높일 수도 있습니다.
이 글을 통해 각 메서드의 역할을 명확히 정리했다면, 이제 REST API 문서를 읽는 것이 훨씬 수월해질 것입니다.

🏷️ 관련 태그 : 파이썬requests, API요청, HTTP메서드, GETPOST차이, PUTPATCH의미, DELETE활용, 응답객체r, RESTAPI, 파이썬웹개발, 타임아웃예외처리