FastAPI Request

 

HTTP Request (HyperText Transfer Protocol)

: 인터넷에서 데이터를 주고받기 위한 규칙(프로토콜)

 

웹 브라우저(크롬 등)에서 주소를 입력하거나 버튼을 누르면, 클라이언트가 서버에게 요청(Request)을 보내고, 서버는 그 요청을 처리한 뒤 응답(Response)을 보내준다. 이 과정을 통해 우리가 보는 것이 웹페이지다. 

 

웹은 처음에 단순히 정보를 제공하기 위한 정적인(Static) 시스템이었다. 하지만 점점 웹을 통해 복잡한 애플리케이션을 만들고자 하는 요구가 높아지면서, 이를 처리하기 위해 다양한 Request와 Response 전송 방식이 개발되었고, 이러한 기술들은 웹 프레임워크(Django, FastAPI 등)의 기반이 되어 오늘날의 동적인 웹을 가능하게 만들었다. 

 

HTTP Request 구성

HTTP 요청은 크게 세 부분으로 구성된다. 

https://www.cloud4y.ru/en/blog/what-are-http-requests/

 

1. 요청 줄 (Request Line)

GET /index.html HTTP/1.1

• GET: 요청 방식(Method)을 의미 (GET, POST, PUT 등)
• /index.html: 요청 대상의 경로(URL)
• HTTP/1.1: 사용하는 프로토콜의 버전

 

2. 헤더 (Headers)

Host: www.example.com  
User-Agent: Mozilla/5.0  
Accept: text/html

요청에 대한 부가 정보를 담고 있다. 예를 들어, 요청을 보낸 브라우저 정보(User-Agent)나 요청하는 데이터 형식(Accept)을 나타낸다. 

 

 

3. 바디 (Body)

POST나 PUT 요청과 같이 데이터를 함께 보낼 때 사용된다. 예를 들어, 로그인 시 ID와 비밀번호를 전송하는 데 사용된다.

 

 

구성 요소

클라이언트	요청을 보내는 주체 (브라우저 등)
서버	요청을 받아 처리하고 응답하는 시스템
Request	클라이언트가 서버에 보내는 요청 메시지
Response	서버가 클라이언트에 보내는 응답 메시지

 

 

Request Parameter

FastAPI에서는 클라이언트가 서버에 요청을 보낼 때, 다양한 방법으로 값을 전달할 수 있다. 특히 Pydantic 모델을 활용하여 데이터 수록, 변환, 검증까지 자동으로 수행할 수 있어 매우 유용하다. Path Parameter, Query Parameter, Request Body, Form Fields, Header, Cookie, File 등의 다양한 request를 지원한다.

 

0. FastAPI의 Request Parameter 처리 방식

FastAPI는 다음과 같은 요청 파라미터를 처리할 수 있는 클래스들을 제공한다.

• Path: URL 경로 파라미터 ex. /items/{time_id}
• Query: URL 쿼리 파라미터 ex. ?q=search
• Body: 요청 본문 데이터
• Form: HTML 폼에서 전달되는 데이터
• File: 업로드 파일 데이터

이러한 클래스들을 통해 전달된 파라미터들은 Pydantic 모델에 매핑되어 자동으로 수록(파싱), 변환, 검증된다.

 

단순한 값이라면 FastAPI가 자동으로 처리해준다. 그러나 복잡한 검증 로직이 필요한 경우, Path, Query 클래스를 명시적으로 선언하여 더욱 정밀한 검사를 수행할 수 있다. 그렇지 않으면 FastAPI가 묵시적으로 처리하여 Pydantic 모델로 자동 변환한다. 

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

 

BaseModel 기반 클래스는 FastAPI에서 요청 데이터를 다루는 핵심 도구다. 클라이언트로부터 받은 JSON 파일의 데이터 검증 절차를 자동으로 해준다. BaseModel을 상속받은 클래스를 만들면 FastAPI는 이 모델을 기준으로, 데이터 파싱 → 데이터 검증 → 변환(필요한 경우)을 수행한다.

 

 

1. Path Parameter

URL 경로 자체에 정보를 담아 서버로 전달하는 방식이다. 이 방식은 주로 특정 자원을 식별할 때 사용된다. 

 

바로, URL 주소의 일부로 데이터를 전달하는 것이다. 예를 들어, http://www.example.com/job/2 라면, 2는 job이라는 자원의 ID를 의미하며, 이 값은 서버로 전달된다.

 

전달 방식은 GET Method를 사용한다. 이 방식은 메시지의 Body 없이도 필요한 정보를 전달할 수 있다. 

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

1. @app.get("/items/{item_id}")
   • item_id는 중괄호 {}로 감싸서 경로 변수로 선언된다.
   • 이 부분은 FastAPI가 요청 URL에서 값을 추출하도록 도와준다.
2. async def read_item(item_id: int)
   • 함수의 인자로 item_id를 받으며, 이 인자의 타입을 int로 지정하면 FastAPI가 해당 값을 자동으로 변환하고 검증해준다.
   • 타입 검사는 내부적으로 Pydantic을 통해 처리된다.

여러 개의 Path Parameter를 사용할 때는 경로가 겹치지 않도록 주의해야 한다. 예를 들어 /items/{item_id}와 /items/latest 같은 경로가 함께 존재하면 충돌할 수 있다. 

 

 

2. Query Parameter

URL 뒤에 ?를 붙이고, key=value 형식으로 데이터를 전달하는 방식이다. 필터링, 검색, 페이징 등과 같은 여러 값을 전달할 때 주로 사용된다. 

 

URL 뒤쪾에 ?를 붙여, 여러 개의 값을 전달할 수 있다. 각 변수는 & 기호로 구분한다. 예를 들어, http://www.example.com/job?id=3&pageIndex=1&sort=ascending이라면 id=3, pageIndex=1, sort=ascending이라는 세 개의 값을 전달한다.

 

전달 방식은 GET Method를 사용하며, 메시지 Body 없이도 데이터를 전달할 수 있다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

• skip: int = 0: 쿼리 파라미터 skip을 int 타입으로 받고, 기본값은 0으로 설정
• limit: int = 10: limit도 마찬가지로 기본값 10을 가진다.
• FastAPI는 이 인자들을 URL의 Query Parameter로 자동 인식해 처리한다.

 

 

3. Request Body

데이터를 메시지의 Body에 담아서 전달하는 방식이다. 주로 POST 또는 PUT 요청에서 사용된다.

 

URL에 값을 담지 않고, Body에 JSON 형식으로 데이터를 담는다. 

FastAPI에서는 Content-Type: application/json으로 설정하면 자동으로 JSON 데이터를 인정식한다. 이 방식은 API에서 가장 일반적으로 쓰이는 데이터 전송 방법 중 하나다.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/")
async def create_item(item: Item):
    return item

• Item(BaseModel) 클래스는 JSON 데이터를 받을 구조를 정의한 것
• create_item 함수의 매개변수로 item: Item을 선언하면,
• FastAPI는 요청 본문(request body)을 자동으로 Item 타입으로 변환해 전달
• 타입이 맞지 않거나 필수 항목이 빠지면, 자동으로 422 에러와 함께 오류 메시지를 반환

요청 예시: 

curl -X 'POST' 'http://localhost:8081/items/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{ "id": "min", "password": "123" }'

 

 

4. Form 

HTML 폼에서 데이터를 전송할때 사용되는 방식이다. 주로 로그인 폼, 회원가입 등 사용자 입력을 받을 때 활용된다.

 

HTML <form> 태그로 데이터를 입력받아 POST 방식으로 전송한다. 

FastAPI에서는 이 데이터를 application/x-www-form-urlencoded 형식으로 처리한다. Body에 데이터를 key=value 형식으로 담는다. 

 

Form 데이터 예시: 

<form action="/login" method="POST">
  <input type="text" name="id" value="min">
  <input type="text" name="password" value="123">
  <input type="submit" value="제출">
</form>

 

사용자가 "제출" 버튼을 누르면 입력한 값들이 POST 방식으로 전송된다.

 

FastAPI는 이런 HTML Form 데이터를 Form() 클래스를 통해 처리할 수 있다.

from fastapi import FastAPI, Form
from typing import Annotated

app = FastAPI()

@app.post("/login/")
async def login(
    username: str = Form(),
    email: str = Form(),
    country: Annotated[str, Form()] = None
):
    return {
        "username": username,
        "email": email,
        "country": country
    }

• username, email: 필수 입력값 → Form()으로 선언
• country: 선택 입력값 → Annotated + Form() 조합으로 Optional하게 처리
• FastAPI는 자동으로 application/x-www-form-urlencoded 타입의 데이터를 읽어들여 각각의 인자에 매핑한다.

 

FastAPI에서 Request 객체 활용하기 

FastAPI에서는 Request 객체를 통해 사용자의 HTTP 요청에 대한 모든 정보를 받아올 수 있다. 클라이언트 IP부터 요청 메서드, 헤더, 파라미터 등 다양한 정보를 추출할 수 있어, 고급 API 로직을 작성할 때 유용하다.

 

Request 객체

Request는 FastAPI에서 요청에 대한 메타 정보를 담고 있는 객체다. 이를 함수의 인자로 선언하면 다양한 요청 정보를 사용할 수 있다. 

 

from fastapi import FastAPI, Request

app = FastAPI()

@app.get("/items")
async def read_item(request: Request):
    client_host = request.client.host
    headers = request.headers
    query_params = request.query_params
    url = request.url

    print("path param:", request.path_params)
    print("http method:", request.method)
    print("headers:", headers)

    return {
        "client_host": client_host,
        "headers": headers,
        "query_params": query_params,
        "url": str(url),
    }

 

주요 속성과 메서드

request.method	HTTP 메서드(GET, POST 등)
request.url	요청된 전체 URL
request.headers	헤더 정보 (딕셔너리 형태)
request.cookies	쿠키 정보 (딕셔너리 형태)
request.client	클라이언트 IP 주소 및 포트
request.query_params	쿼리 파라미터 정보
request.path_params	경로 파라미터 정보
await request.json()	JSON 형태의 Body 데이터
await request.form()	Form 데이터