[Spring Boot] Path Variable, Query Parameter, Request Body

Path Variable, Query Parameter, Request Body는 API 개발을 하다보면 반드시 알아야 하는 내용이다. 그리고 각각을 어느 상황에 써야 하는지도 확실하게 알고 사용을 해야 하는데, 얼마 전까지만 해도 확실한 이해 없이 그냥 사용만 하고 있다는 느낌을 받았다. 그때 알아보며 정리한 내용을 공유하려고 한다!

Path Variable

---

Path Variable

Path Variable은 URL 경로의 일부로 포함되는 변수이다. 특성 리소스를 식별할 때 사용하며, 필수 값이기 때문에 누락 시 404 에러가 발생한다. 계층적인 리소스 관계를 표현할 수 있기 때문에 RESTful 설계 원칙에 부합한다.
또한, URL 기반이기 때문에 캐싱에 유리하고 CDN에 활용할 수 있다는 장점이 있다.

다음과 같이 API 버전을 Path Variable로 관리할 수도 있다.

@GetMapping("/v{version}/users/{userId}")

RESTful 설계 원칙

Path Variable을 제대로 활용하려면 RESTful 설계 원칙을 이해하면 좋다.

1. 리소스 기반 URL 설계

   GET /users/123
   POST /users

   • 복수형으로 목록을 표현한다. (ex. users, orders)
   • 이미 HTTP 메서드가 동사 역할을 하기 때문에 URI에 동사를 사용하는 것은 지양한다. 경우에 따라 동사를 사용하는 경우도 있다.
   • 단어 구분이 필요한 경우에는 - 사용을 권장한다. (user-profiles)
2. HTTP 메서드 활용
   • GET : 조회 (멱등성 O, 안전함)
   • POST : 생성 (멱등성 X)
   • PUT : 전체 수정 (멱등성 O)
   • PATCH : 부분 수정 (멱등성 X)
   • DELETE : 삭제 (멱등성 O)
3. 계층적 리소스 표현 - Path Variable
   • GET /users/123/orders - 123번 사용자의 주문 목록
   • GET /departments/5/employees - 5번 부서의 직원 목록
     
     

예시

// URI
GET /users/{userId}

// Spring Boot
@GetMapping("/users/{userId}")
public User getUser(
		@PathVariable Long userId
) {...}

주의할 점

1. URL 구조의 일관성을 유지해야 한다. (복수형 명사 사용 등)
2. Path Variable 검증을 해야 한다.
3. 특수 문자가 들어온 경우 인코딩 처리가 필요하다.
4. 선택적 매개변수는 Path Variable이 아닌 Query Parameter를 사용해야 한다.
5. 계층이 너무 깊은 경우에는 유지보수가 어렵다.
   ex) /products/{category}/{subcategory}/{brand}
6. 날짜나 상태값 같이 자주 바뀌는 값은 Query Parameter가 더 적합하다.
   
   

보안 관련 주의사항

• SQL Injection 방지를 위한 숫자/문자 검증이 필요하다.
• Directory Traversal 공격 방지를 위한 ../ 패턴 체크가 필요하다.
  
  

Query Parameter

---

Query Parameter

Query Parameter는 URL 뒤에 ?key=value 형태로 전달되는 매개변수다. 선택적 조건이나 필터링에 주로 사용되며, 데이터 조회 시 유연성을 제공한다. 페이징을 사용하면 대용량 데이터를 효율적으로 처리할 수 있다.

Query Parameter 예시

// URI
GET /users?page=1&size=10

// Spring Boot
@GetMapping("/users")
public List<User> getUsers(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "10") int size
) {...}

주의할 점

1. 파라미터 검증 및 기본값 설정을 해야 한다.
2. Path Variable과 마찬가지로 단어 구분은 -으로 하는 것을 권장한다.
3. URL 길이 제한이 있기 때문에 대용량 데이터는 전송할 수 없다. (브라우저별 약 2048자)
4. 복잡한 객체 구조는 Query Parameter로 표현하기 어렵다.
5. URL이 노출되기 때문에 민감한 정보는 사용할 수 없다.
6. 페이징과 정렬 요청, 응답값을 표준화해야 한다.
   
   

보안 관련 주의사항

• XSS 방지를 위한 특수문자 이스케이프가 필요하다.
• SQL Injection 방지 처리가 필요하다.
• 민감한 정보(비밀번호, 토큰 등) 사용을 금지해야 한다.
  
  

Request Body

---

Request Body

HTTP 요청 본문에 포함되는 데이터로, JSON, XML, Form Data 등 다양한 형태로 보낼 수 있어 복잡하고 민감한 데이터를 안전하게 전송할 수 있다.

주로 POST, PUT, PATCH, DELETE에서 사용된다.

• POST : 새로운 리소스 생성 (HttpStatus 201 권장)
• PUT : 전체 리소스 교체
• PATCH : 부분 업데이트
• DELETE : 삭제하면서 추가 정보가 필요한 경우
  
  

Request Body 예시

// URI 및 Request Body
POST /users
Content-Type: application/json

{
  "name" : "가나다",
  "email" : "ganada@example.com",
  "age" : 30
}

// Spring Boot
@PostMapping("/users")
public User createUser(
		@RequestBody CreateUserRequest request
) {...}

주의할 점

1. 데이터 검증 및 보안 처리를 해야 한다. (@Valid 사용 권장)
2. Content-Type을 명시적으로 처리해야 한다.
3. 요청 크기 제한을 설정해야 한다.
4. GET 요청에서는 Request Body를 보낼 수 없는 경우가 많다.
5. 동일한 요청을 식별하기 어렵기 때문에 캐싱 효율이 떨어진다.
   
   

보안 관련 주의사항

• JSON Payload 크기 제한을 설정해야 한다.
• 악성 스크립트 필터링을 적용해야 한다.
• 파일 업로드 시 확장자/크기 제한이 필요하다.
  
  

Path Variable vs Query Parameter vs Request Body

---

	Path Variable	Query Parameter	Request Body
위치	URL 경로 내	URL 뒤 ?key=value	HTTP Body
필수 여부	필수	선택적	메서드에 따라 다름
보안	보통	낮음 (URL 노출)	높음
복잡도	단순	단순~보통	복잡
캐싱	유리	유리	불리
테스트	URL로 가능	URL로 가능	도구 필요

참고 자료

---

What is REST?: REST API Tutorial
HTTP 상태 코드 - HTTP | MDN
Getting Started | Building REST services with Spring