HTTP 요청의 3가지 데이터 전송 방식 - Params, Query, Body

웹 개발과 API 설계에서 데이터 전송은 핵심적인 부분이다. HTTP 프로토콜은 클라이언트와 서버 간 통신을 위한 다양한 방법을 제공하며, 그 중에서도 Path Parameter, Query String, Request Body는 가장 널리 사용되는 세 가지 데이터 전송 방식이다. 

 

1. Path Parameter (Path variable)

Path parameter는 웹 초창기부터 존재했지만, 2000년 Roly Fielding의 REST 아키텍처 스타일이 소개되면서 더욱 체계화되었다.  Restful API 설계 원칙에서는 리소스(Resource)를 URL 경로의 일부로 표현하는 방식을 권장했고, 이것은 자원 지향 아키텍처(Resource-Oriented Architecture)의 핵심 개념이 되었다. 

 

Path parameter는 웹 리소스의 계층 구조를 직관적으로 표현할 수 있게 해주며, 특정 자원을 명확하게 식별하는 목적으로 발전했다. 초기 웹 애플리케이션에서는 정적 페이지나 간단한 스크립트만 제공했지만, 웹이 복잡해지고 동적 콘텐츠가 증가하면서 리소스를 구조적으로 관리할 필요성이 커졌고, Path parameter가 그 해결책이 되었다. 

 

특징

Path parameter는 URL 경로의 일부로 포함되며, 일반적으로 경로 세그먼트로 표현된다. 이러한 매개변수는 URL 구조에 직접 통합되어 있어 경로의 일부처럼 보이지만 실제로는 동적인 값을 나타낸다. 서버 측에서는 라우팅 시스템을 통해 이러한 매개변수를 추출하고 처리한다. 

https://api.example.com/users/123/posts/456

 

위 URL에서 123과 456은 각각 사용자 ID와 게시물 ID를 나타내는 Path parameter이다. 서버는 이 값을 경로에서 추출하여 해당 리소스를 식별하고 적절한 응답을 생성한다. 

 

대부분의 웹 프레임워크는 Path Parameter를 쉽게 정의하고 접근할 수 있는 방법을 제공한다. 예를 들어 Express에서는 :paramName 구문을 사용하여 정의할 수 있다. 

app.get('/users/:userId/posts/:postId', (req, res) => {
  const userId = req.params.userId;
  const postId = req.params.postId;
  // 로직 
});

 

Path Parameter가 적합한 경우 

1. 특정 리소스(엔티티나 객체)를 고유하게 식별해야 할 때 (ID, UUID 등)

GET /products/123       // ID가 123인 상품의 상세 정보 조회

 

2. 부모-자식 관계와 같은 계층 구조를 표현할 때 

GET /departments/marketing/teams/design    // 마케팅 부서의 디자인 팀 정보

 

3. 리소스의 생성, 조회, 수정, 삭제와 같은 CRUD 작업을 수행할 때 

DELETE /comments/789      // ID가 789인 댓글 삭제

 

Path parameter는 URL 경로의 일부이므로 리소스의 위치나 식별자를 명확하게 표현하는 것에 장점이 있다. 

 

장점	단점 및 한계
- 의미론적으로 명확한 URL 구조 제공 - RESTful 원칙에 부합하는 자원 중심 설계 가능  - 자원의 계층 구조를 직관적으로 표현 - 대부분의 웹 서버와 프레임워크에서 기본적으로 지원	- URL 길이 제한으로 인한 데이터 양 제약  - URL에 노출되므로 민감한 정보에는 부적합  - 선택적 매개변수를 표현하기 어려움 - 복잡한 필터링이나 검색 조건을 표현하기에는 적합하지 않음

 

 

Query String (Query Parameter)

Query String 역시 웹의 초창기 시절부터 URL 구성 요소로 존재해 왔다. Query String은 주로 HTML 폼에서 GET 요청을 처리하기 위한 방법으로 시작되었다. 웹 초기에는 정적 페이지가 대부분이었으나 사용자의 입력에 따라 다른 결과를 보여주는 동적 웹 페이지의 필요성이 점점 커졌고, Query String은 이러한 동적 콘텐츠 생성을 위한 매개변수를 전달하는 표준화된 방법으로 발전하게 되었다. 특히 검색 엔진이 등장하면서 검색어, 필터링 옵션 등을 전달하기 위한 메커니즘으로 Query String의 중요성이 더욱 커졌다. 

 

특징 

Query String은 URL의 끝 부분에 위치하며,  '?' 기호로 시작하고 '&' 기호로 여러 매개변수를 구분한다. 각 매개변수는 키-값 쌍으로 구성되며, '=' 기호로 연결된다. 

https://example.com/search?query=restful+api&category=web&page=2

 

위 URL에서 query=restful+api, category=web, page=2는 모두 Query String 매개변수이다. 매개변수는 서버 측에서 요청 객체를 통해 접근할 수 있다. 

app.get('/search', (req, res) => {
  const query = req.query.query;
  const category = req.query.category;
  const page = req.query.page;
  // 로직
});

 

Query String 값은 URL 인코딩을 통해 안전하게 전송된다. 예를 들어 공백은 '+' 또는 '%20'으로, 특수 문자는 해당 ASCII 코드의 16진수 값 앞에 %를 붙여 인코딩된다. 대부분의 서버사이드 프레임워크는 Query String을 자동으로 파싱해서 개발자가 쉽게 접근할 수 있도록 지원한다. 

 

Query String이 적합한 경우

1. 다양한 조건으로 데이터를 검색하거나 필터링할 때 

GET /products?category=electronics&price_min=100&price_max=500&brand=samsung

 

2. 결과의 순서나 페이지 분할을 제어할 때 (정렬 & 페이지네이션)

GET /articles?sort=date&order=desc&page=3&limit=20

 

3. 기본값이 있는 선택적 설정이나 옵션을 지정할 때 

GET /reports?format=pdf&include_charts=true&period=monthly

 

4. 상태를 유지하지 않는 웹 애플리케이션에서 상태 정보를 URL에 포함할 때 

GET /dashboard?view=compact&section=analytics

 

5. 사용자가 특정 상태나 뷰를 북마크할 수 있도록 할 때

GET /map?lat=37.7749&lng=-122.4194&zoom=12

 

Query String은 특히 GET 요청에서 리소스를 필터링하거나 검색하는 것에 적합하다. 

 

장점	단점 및 한계
- 선택적 매개변수를 명확하게 표현 가능 - 복잡한 필터링과 검색 조건을 표현하기 용이함 - HTML 폼의 GET 메서드와 자연스럽게 통합할 수 있음  - GET 요청의 경우 캐싱 가능	- URL에 노출되므로 민감한 정보에는 부적합  - 복잡한 데이터 구조를 표현하기는 어려움  - 인코딩/디코딩 과정에서 오류 발생 가능 - 대용량 데이터 전송에는 비효율적

 

 

Request Body 

Request Body는 HTTP/1.0이 1996년에 공식화되면서 HTTP 프로토콜의 중요한 부분이 되었다. 특히 POST 메서드의 등장과 함께 Request Body의 중요성도 커졌다. POST 메서드는 새로운 리소스를 생성하거나 기존 리소스를 수정하는데 사용되는데, 이 과정에서 대량의 데이터나 복잡한 객체를 전송하는 경우가 많았다. 따라서 URL의 길이 제한이나 보안 문제를 피하면서도 효율적으로 데이터를 전송할 수 있는 메커니즘이 필요했고, Request Body가 그 해결책이 되었다. 

 

XML과 JSON 같은 데이터 형식과 함께 Request Body는 더욱 중요해졌고, 특히 2000년대 중반 AJAX의 등장과 API 중심의 웹 개발의 확산으로 현대 웹 개발의 필수적인 부분이 되었다. 

 

특징

Request Body는 HTTP 요청의 메시지 본문에 포함되는 데이터로, HTTP 헤더 다음에 빈 줄로 구분되어 위치한다. 다양한 형식의 데이터를 포함할 수 있으며, Content-Type 헤더를 통해 데이터 형식을 지정한다. 

 

가장 일반적인 Content-Type 값은 다음과 같다. 

• application/json: JSON 형식의 데이터
• application/xml: XML 형식의 데이터 
• application/x-www-form-urlencoded: HTML 폼 데이터 (키-값 쌍)
• multipart/form-data: 파일 업로드를 포함한 폼 데이터 
• text/plain: 일반 텍스트 

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 91

{
  "name": "홍길동",
  "email": "hong@naver.com",
  "role": "admin",
  "department": "IT"
}

 

대부분의 웹 프레임워크와 라이브러리는 Request Body를 자동으로 파싱하는 기능을 제공한다. 

app.post('/api/users', (req, res) => {
  const userData = req.body;
  // 로직
});

 

Request Body가 적합한 경우

1. POST, PUT. PATCH 요청을 통해 새 리소스를 생성하거나 기존 리소스를 수정할 때

POST /api/projects
{
  "title": "신규 프로젝트",
  "description": "프로젝트 정보를 업데이트합니다",
  "members": [101, 102, 103],
  "deadline": "2025-04-02"
}

 

2. 중첩된 객체나 배열과 같은 복잡한 데이터 구조를 전송할 때 

POST /api/orders
{
  "customer": {
    "id": 12345,
    "shippingAddress": {
      "street": "서울시 강남구 테헤란로 123",
      "city": "서울",
      "zipCode": "12345"
    }
  },
  "items": [
    { "productId": "p-001", "quantity": 2, "price": 25000 },
    { "productId": "p-002", "quantity": 1, "price": 35000 }
  ],
  "paymentMethod": "credit_card"
}

 

3. 대량의 텍스트 데이터나 파일을 전송할 때 

POST /api/documents
Content-Type: multipart/form-data

(파일 데이터)

 

4. 비밀번호나 개인 정보와 같은 민감한 데이터를 전송할 때

POST /api/auth/login
{
  "username": "user123",
  "password": "secureP@ssword"
}

 

5. 여러 개의 작업을 하나의 요청으로 처리할 때 

POST /api/batch
{
  "operations": [
    { "type": "create", "resource": "tasks", "data": { ... } },
    { "type": "update", "resource": "projects", "id": 5, "data": { ... } },
    { "type": "delete", "resource": "comments", "id": 123 }
  ]
}

 

장점	단점 및 한계
- URL 길이 제한에 영향을 받지 않는다. - 중첩 객체, 배열 등 복잡한 데이터 구조를 표현하는 것이 가능하다.  - 대용량 데이터와 파일 전송에 적합하다.  - URL에 노출되지 않아 상대적으로 보안성이 높다.  - 다양한 데이터 형식을 지원한다.	- GET 요청에서는 일반적으로 사용되지 않는다.  - POST 요청의 경우 캐싱이 어렵다.  - URL 만으로는 요청 내용을 파악할 수 없기 때문에 디버깅이 어렵다.  - 추가적인 파싱 단계가 필요할 수 있다.

 

 

세 가지 방식의 비교 분석 

1) 데이터 가시성과 보안 측면

• Path parameter와 Query String은 모두 URL의 일부이므로 브라우저 주소창, 서버 로그, 브라우저 히스토리 등에 노출된다. 따라서 디버깅에는 유리하지만 민감한 정보를 전송하기에는 적합하지 않다. 특히 비밀번호, 토큰, 개인 식별 정보와 같은 데이터는 URL을 통해 전송하면 보안 위험이 크다. 반면 Request Body는 URL에 노출되지 않기 때문에 상대적으로 보안성이 높다. 그러나 서버 로그나 디버깅 도구에는 노출될 수 있기 때문에 완전한 보안을 보장하지는 않는다. 
• Path parameter와 Query String은 URL 길이 제한에 영향을 받는다. 브라우저 및 서버, 프록시 등에 따라 다르지만 일반적으로 URL은 2048자를 넘지 않는 것이 권장된다. 이러한 제한은 대용량 데이터나 복잡한 구조를 전송할 때 문제가 될 수 있다. 반면 Request Body는 URL 길이 제한에 영향을 받지 않기 때문에 서버 설정에 따라 더 큰 용량의 데이터를 전송할 수 있다. 따라서 대용량 파일 업로드가 필요할 때는 Request Body를 사용하는 것이 적합하다. 

2. HTTP 메서드 호환성 측면 

• 각 데이터 전송 방식은 특정 HTTP 메서드와 더 잘 어울린다. 
• Path Parameter: 모든 HTTP 메서드와 함께 사용 가능하지만 주로 GET, DELETE와 같이 특정 리소스를 식별하는 데 사용된다. 
• Query String: 역시 모든 HTTP 메서드와 함께 사용 가능하지만, 주로 GET 요청에서 필터링, 정렬, 페이지네이션에 사용된다. 
• Request Body: 주로 POST, PUT, PATCH와 같이 데이터 생성/수정 메서드와 함께 사용된다. GET 메서드는 설계 의도상 Request Body를 사용하지 않도록 고안되었기 때문에 웬만하면 사용하지 말자. 

3. 인코딩과 데이터 형식 

• Path Parameter와 Query String은 URL의 일부이므로 URL 인코딩을 따라야 한다. 특수 문자, 유니코드 문자, 공백 등이 포함된 데이터를 전송할 때 추가적인 인코딩/디코딩 단계가 필요함을 의미한다. 
• Request Body는 Content-Type 헤더에 따라 다양한 형식과 인코딩을 지원한다. JSON, XML, form data, 바이너리 등 각 형식에 맞는 인코딩을 적용할 수 있어 복잡한 데이터 구조나 다국어 콘텐츠를 처리하는 것에 강점이 있다. 

 

 

이 세 가지 방식은 상호 배타적이지 않으며, 웹 애플리케이션과 API를 제대로 잘 설계하기 위해서는 각 방식을 상황에 맞게 적절히 조합하여 사용하는 것이 중요하다. 

 

핵심 요약

- Path Parameter는 RESTful 원칙에 따라 리소스를 명확하게 식별하는 데 적합하다.
- Query String은 필터링, 정렬, 페이지네이션과 같은 작업에 적합하다.
- Request Body는 복잡한 데이터 구조나 대용량 데이터 전송에 가장 적합하다.