처음 시작하는 FastAPI

MMM._.MMM·2025년 11월 10일

처음 시작하는 FastAPI

목록 보기

3/5

처음 시작하는 FastAPI 책을 읽으면서 책 내용을 정리한 내용입니다.

PART 2-2

HTTP 본문(Body)

HTTP Body는 클라이언트와 서버 간에 실제 데이터를 전송하는 영역입니다.

Body의 역할 및 위치
HTTP 요청과 응답 모두 Body를 가질 수 있습니다.

Request Body(요청 본문): 클라이언트가 서버로 전송하는 데이터를 담습니다.
(ex. POST or PUT요청으로 사용자 정보, 게시글 내용등을 서버에 보낼때 사용)
Response Body(응답 본문): 서버가 클라이언트에게 요청 처리 결과로 반환하는 데이터를 담습니다.
(ex. GET 요청으로 조화된 데이터(JSON), HTML 페이지, 이미지 파일 등을 클라이언트에 보낼때 사용

Body의 중요성
HTTP Body에 데이터를 담을 때는 해당 데이터가 어떤 형식인지 Content-Type 헤더를 통해 서버에 알려줘야합니다.
FastAPI를 포함한 최신 웹 애플리케이션에서 가장 많이 사용되는 2가지 형식은 아래와 같습니다.
1. JSON(JavaScript Object Notation)

Content-Type: application/json

특징: 가장 널리 사용되는 데이터 교환 형식입니다. 가볍고 사람이 읽기 쉬우며 다양한 프로그램 안에서 쉽게 파싱할 수 있습니다.

FastAPI에서의 역할: FastAPI가 가장 선호하는 형식입니다. Pydantic모델을 사용하여 요청 Body를 자동으로 검증하고 파싱합니다.

JSON 예시
json {
    "name": "MMM._.MMM",
    "age": 26,
}

Form Data(폼 데이터)

Content-Type: application/x-www-form-urlencoded or multipart/form-data

특징

x-www-form-urlencoded: 웹 브라우저에서 form태그의 기본 전송 방식과 유사합니다. Key-Value 형태의 데이터를 URL 인코딩하여 전송합니다.
-multipart/form-data: 파일을 업로드할 때 주로 사용됩니다. 텍스트와 파일을 동시에 보낼 수 있도록 데이터를 여러부분(파트)으로 나누어 전송합니다.

Form Data 예시 (application/x-www-form-urlencoded)
username=user123&password=secret,

HTTPie를 사용한 Body 전송 예시
HTTPie를 사용할 때 Body 데이터를 전송하는 것은 매우 직관적입니다.

JSON Body 전송 (가장 일반적)
HTTPie는 기본적으로 JSON Body를 지원합니다. 별도의 헤더 지정 없이 Key-Value 형식으로 데이터를 입력하면 자동으로 JSON으로 변환하여 전송합니다.

#FastAPI 서버의 POST /items 엔드포인트로 JSON 데이터 전송
http POST http://127.0.0.1:8000/items name="New Item" price:=10000

#name='...': 문자열 값 전송
#price:=10000: 숫자(정수/실수) 값 전송

Form Data 전송 (파일 업로드등)
Form Data를 전송하거나 파일을 업로드할 때는 -f or --form 옵션을 사용합니다.

#Form Data (application/x-www-form-urlenmcoded) 전송 예시
http -f POST http://127.0.0.1:8000/login username=user1 password=secret

#파일 업로드 (multipart/form-data) 예시
http -f POST http://127.0.0.1:8000/upload file@/path/my/profile/img/image.jpg

HTTP 헤더(Request/Response Headers)

개념
요청 또는 응답에 대한 메타데이터 즉 부가정보를 담는 영역입니다. 클라이언트와 서버가 통신을 위해 필요한 환경, 데이터 형식, 보안, 캐시 등의 정보를 교환하는데 사용됩니다.

핵심 포인트(기능적 분류)
HTTP 헤더는 해당 역할에 따라 크게 4가지로 분류되며 이 중 개발에서 중요한 역할은 다음과 같습니다.

헤더 유형	목적 및 주요 예시	FastAPI/ 웹 개발 활용
1. 인증/보안	클라이언트의 신원 확인 및 보안 관련 정보	Authorization(JWT Token), Cookie, Set-Cookie, 민감 정보 전송시 반드시 TLS(HTTPS)가 필요합니다.
콘텐츠 협상	Body 데이터의 형식, 언어, 인코딩 등을 정의	Content-Type(Boby 데이터 형식 지정), Accept(클라이언트가 원하는 응답 형식)
접속/흐름 제어	연결 상태, 캐시, 압축, 리다이렉션 제어	Cache-Control, Connection, ETag, If-Modified-Since, CORS관련 헤더
정보 전달	요청을 보낸 클라이언트/서버에 대한 기본 정보	User-Agent(클라이언트 브라우저/앱 정보), Server(사용된 웹 서버 종류)

다중요청데이터(Form + File / multipart)

multipart/form-data 는 하나의 요청 본문(Body)을 여러개의 파트로 나누어 전송하는 표준 방식입니다. 각 파트는 아래와 같은 특징을 가지고 있습니다.

각 파트가 서로 섞이지 않도록 경계선(Boundary) 으로 명확하게 구분됩니다.
각 파트에는 고유한 Content-Disposition헤더가 있어 해당 파트가 일반 폼 데이터인지 파일인지를 서버에게 알려줍니다.

주로 사용되는 경우

파일 업로드: 이미지, 문서, 동영상등 이진 파일을 서버에 보낼 때 필수적으로 사용됩니다.
파일과 텍스트의 동시 전송: 파일과 함께 해당 파일의 제목, 설명 등의 메타데이터(일반 텍스트)를 한번의 요청으로 전송할 때 사용됩니다.

요청 권장사항

아래의 내용은 몇가지 권장사항입니다.

URL에 인수를 전달할 때는 RESTful 가이드라인을 따르는 것이 표준 관행입니다.
쿼리 문자열은 대개 페이지네이션 같은 선택적 인수를 제공하는데 사용합니다.
본문은 대개 전체 모델이나 부분 모델과 같이 더 큰 입력에 사용합니다.

각 경우마다 데이터 정의에 TypeHint를 제공하면 Pydantic이 자동으로 인자의 타입을 검사해 모든 인자가 존재하고 올바른지 확인할 수 있습니다.

HTTP 응답 헤더

주요 HTTP 응답 헤더와 역할
응답 헤더는 클라이언트가 서버로부터 받은 데이터를 어떻게 처리하고 해석해야 하는지를 지시합니다.

1. 콘텐츠 및 형식 관련 헤더
이 헤더들은 응답 본문(Body)에 담긴 데이터의 종류와 특성을 설명합니다.
- Content-Type

역할: 응답 본문의 미디어 타입(MIME Type)을 지정합니다. 클라이언트는 이 정보를 바당으로 본문을 올바르게 해석합니다.

- Content-Length

역할: 응답 본문의 바이트 단위 크기를 나타냅니다. 클라이언트가 응답을 완전히 받았는지 확인하는 데 사용됩니다.

- Content-Encoding

역할: 응답 본문에 적용된 압축 방식을 나타냅니다.

2. 캐싱 및 유효성 관련 헤더
이 헤더들은 클라이언트나 중간 프록시 서버가 응답을 저장(캐싱)하고 다음에 동일한 요청을 할 때 저장된 응답이 여전히 유효한지 확인하는데 사용됩니다.
- Cache-Control

응답을 캐시할지 여부와 캐시의 수명등을 명시적으로 제어합니다. 웹 성능 최적화에 매우 중요합니다.

- ETag(Entity Tag)

특정 버전의 리소스를 식별하는 고유한 토큰입니다. 클라이언트가 다음 요청시 If-None-Match헤더와 함께 전송하여 리소스가 변경되지 않았다면 304 Not Modified응답을 받게 합니다

- Expires

캐시가 만료되는 정확한 날짜와 시간을 지정합니다.

3. 보안 및 연결 관련 헤더
이 헤더들은 보안 정책을 강제하거나 연결 방식을 제어합니다.

Set-Cookie: 서버가 클라이언트에게 쿠키를 저장하도록 지시합니다. 쿠키는 사용자 인증 상태나 세션 정보를 유지하는 데 사용됩니다.

주의 사항
보안을 위해 HttpOnly, Secure, SameSite 속성을 함께 설저으하는 것이 강력합니다.
Access-Conttrol-Allow-Origin (CORS): 클라이언트가 요청을 보낸 출처(Origin)외의 다른 출처에서 해당 리소스에 접근하는 것을 허용할지 여부를 브라우저에게 알립니다.
Location: 클라이언트에게 ㅡ다른 URL로 리다이렉트해야함을 알립니다. 주로 301 Moved Permanetly 또는 302 Found응답코드와 함께 사용됩니다.