Request, Query String, Path Parameters 상세 개념
API 개발에서 Request, Query String, Path Parameters는 각각 다른 역할과 의미를 가집니다. 아래에서 각 용어의 개념과 차이, 그리고 언제 사용하는지 상세히 설명합니다.
Request (요청)
- 클라이언트(브라우저, 앱 등)가 서버(API)에 무언가를 요청하는 행위 전체를 의미합니다.
- HTTP 메서드(GET, POST, PUT, DELETE 등), URL, 헤더, 바디, 파라미터 등으로 구성됩니다.
HTTP 주요 메서드(GET, POST, PUT, DELETE, PATCH) 설명
API 개발에서 자주 사용하는 HTTP 메서드들은 각각의 목적과 동작 방식이 다릅니다.
아래 표와 함께 각 메서드의 개념과 차이점을 상세히 설명합니다.
| 메서드 | 주요 목적 | 특징 및 사용 예시 |
|---|---|---|
| GET | 리소스 조회 | 서버의 데이터를 읽어올 때 사용- 서버의 상태나 데이터 변경 없음- URL에 파라미터 전달 가능- 안전하고, 멱등성 있음 |
| POST | 리소스 생성/처리 | 서버에 데이터를 전송해 새 리소스 생성- 주로 등록, 처리, 전송에 사용- 요청 본문(Body)에 데이터 포함- 멱등성 없음 |
| PUT | 리소스 전체 수정/생성 | 지정한 리소스를 완전히 대체- 리소스가 없으면 새로 만듦(생성)- 클라이언트가 리소스 위치 지정- 멱등성 있음 |
| PATCH | 리소스 부분 수정 | 리소스의 일부만 변경- 요청 데이터만 적용(부분 업데이트)- 멱등성은 보장되지 않음 |
| DELETE | 리소스 삭제 | 서버에서 지정한 리소스를 삭제- 멱등성 있음(여러번 호출해도 결과 동일) |
GET
- 서버에서 데이터를 "조회"할 때 사용합니다.
- 예: 게시글 목록 가져오기, 사용자 정보 조회 등
- 서버의 상태나 데이터에 영향을 주지 않으므로 안전(safe)하며, 같은 요청을 여러 번 해도 결과가 변하지 않는 멱등성(idempotent)을 가집니다.
POST
- 서버에 데이터를 "전송"해서 새로운 리소스를 생성하거나, 데이터 처리를 요청할 때 사용합니다.
- 예: 회원 가입, 게시글 작성 등
- 요청할 때마다 새로운 데이터가 생성될 수 있으므로 멱등성이 없습니다.
PUT
- 지정한 리소스를 "완전히 대체"하거나, 없으면 새로 만듭니다.
- 예: 회원 정보 전체 수정, 특정 게시글 전체 덮어쓰기 등
- 같은 요청을 여러 번 보내도 결과가 같으므로 멱등성을 가집니다.
PATCH
- 리소스의 "일부만 부분적으로 수정"할 때 사용합니다.
- 예: 회원 정보 중 나이만 변경, 게시글 제목만 수정 등
- PUT과 달리 전체를 덮어쓰지 않고, 전달된 필드만 변경합니다.
DELETE
- 서버에서 특정 리소스를 "삭제"할 때 사용합니다.
- 예: 게시글 삭제, 회원 탈퇴 등
- 여러 번 요청해도 결과가 같으므로 멱등성을 가집니다.
PUT과 PATCH의 차이
- PUT: 리소스 전체를 새 데이터로 "완전히 대체"합니다. 기존에 없으면 새로 생성할 수도 있습니다.
- PATCH: 리소스의 일부만 "부분적으로 수정"합니다. 전달된 데이터만 반영되고 나머지는 그대로 유지됩니다.
- GET: 데이터 조회(읽기)
- POST: 데이터 생성/처리(쓰기)
- PUT: 데이터 전체 수정/생성(덮어쓰기)
- PATCH: 데이터 부분 수정(부분 변경)
- DELETE: 데이터 삭제
각 메서드는 RESTful API 설계에서 역할이 명확히 구분되어 있으니, 목적에 맞게 사용하는 것이 중요합니다.
Query String (쿼리 스트링, Query Parameter)
- URL에서 ? 뒤에 오는 key=value 형태의 문자열입니다.
- 여러 개의 파라미터는 &로 구분합니다.
- 예시:
/search?q=abc&page=2 - 여기서
q=abc,page=2가 Query Parameter입니다. - 용도:
- 데이터 필터링, 정렬, 검색 등 옵션을 전달할 때 사용합니다.
- 예: 특정 조건에 맞는 게시글 목록, 특정 사용자의 게시글 등
- URL의 끝에 위치
- key와 value 쌍으로 여러 개 전달 가능
- 선택적(optional)인 값이 많음
Path Parameter (패스 파라미터, Path Variable)
- URL 경로의 일부를 변수처럼 사용하는 방식입니다.
- 예시:
/users/123
/products/45 - 여기서
123,45가 Path Parameter입니다. - 용도:
- 특정 리소스(데이터)를 고유하게 식별할 때 사용합니다.
- 예: 특정 사용자, 특정 상품, 특정 게시글 등[1][3][4][5].
- 특징:
- URL 경로 중간에 위치.
- 슬래시(
/)로 구분. - 주로 필수(required) 값.
- RESTful API에서 리소스 식별에 적합.
Query String vs Path Parameter 비교
| 구분 | Query String (Query Parameter) | Path Parameter (Path Variable) |
|---|---|---|
| 위치 | URL의 끝, ? 뒤에 key=value 쌍 | URL 경로의 일부, 슬래시(/)로 구분 |
| 예시 | /posts?user=abc&sort=desc | /users/123 |
| 용도 | 필터링, 정렬, 옵션 전달 | 특정 리소스(고유 데이터) 식별 |
| 값의 성격 | 선택적(optional), 여러 개 가능 | 필수(required), 보통 1개 또는 소수 |
| RESTful 의미 | 리소스의 속성/옵션 | 리소스의 고유 ID |
언제 각각을 써야 할까?
-
Path Parameter:
- 고유한 리소스(데이터)를 명확히 지정할 때
예:/users/123(ID가 123인 사용자 조회)
- 고유한 리소스(데이터)를 명확히 지정할 때
-
Query String:
- 리소스의 일부만 필터링, 정렬, 검색할 때
예:/posts?user=abc(작성자가 abc인 게시글 목록)
- 리소스의 일부만 필터링, 정렬, 검색할 때
실무 예시
- 모든 게시글 목록:
/posts - 특정 게시글 조회:
/posts/100
(여기서 100은 Path Parameter) - 특정 사용자의 게시글만 보기:
/posts?user=abc
(user=abc는 Query Parameter)
요약
- Request: 서버에 보내는 전체 요청 행위.
- Query String: URL 끝에 붙는 key=value 옵션, 필터/검색/정렬 등에 사용.
- Path Parameter: URL 경로의 일부로 고유 리소스 식별에 사용.
- 차이점: 위치, 용도, 값의 성격에서 다름. RESTful 설계에서 의미가 명확히 구분됨.
API 설계 시, 리소스를 식별할 때는 Path Parameter, 옵션이나 조건을 줄 때는 Query String을 사용하는 것이 일반적입니다.
AI/ML Engineer