[Restful API] Param과 Query의 차이

API를 설계할 때 '나는 과연 param과 query를 적절하게 사용하고 있었던 걸까?' 라는 생각에 공부한 내용을 정리한 글입니다.

Param (path-parameter; 경로 매개변수)

1. 특징

• param은 경로의 일부로 전달되는 값을 의미
• URL의 구조 자체에 포함되어야 합니다.
• API에서 특정 자원(users, bbs, ...)을 식별할 때 사용합니다.

2. 예제

http://host/users/[param]

users에서 [param]의 정보를 호출하는 API URL입니다.

응용 :

• http://host/bbs/:postId - postId 게시물의 제목, 내용 등 정보를 반환
• http://host/users/:userName - userName 유저 a의 id, 성별, 나이 등 정보를 반환
• http://host/invest/:companyName - companyName 회사의 주식 정보를 반환
• http://url/users/:userName/inventory/:inventoryGroupName - userName 유저의 아이템 인벤토리 중 inventoryGroupName에 속한 아이템 정보를 반환

3. 정리

• http://host/invest/:region/:company 같이 region에 국가, company에 회사를 적어 더 세부적인 API를 구성할 수 있습니다.
• param은 url에 꼭 포함되어야 호출이 됩니다.

---

Query (query-parameter; 쿼리 매개변수)

1. 특징

• url의 맨 끝에 ?를 붙여 사용합니다.
• 여러개의 Query를 선택적(optional)으로 사용 가능합니다.
• 여러개의 Query를 사용하기 위해서는 &를 이용해 붙일 수 있습니다.
• API에 존재하지 않는 Query Parameter이더라도 일반적으로 오류가 발생하지 않습니다.

2. 예제

http://host/users?age=25&gender=male

users에서 나이는 25살이면서 성별이 남성인 유저의 데이터만 호출하는 API URL입니다.

응용 :

• http://host/bbs?sort=ascend - 게시판의 정렬 방식을 오름차순으로 정렬된 게시판의 게시물을 반환
• http://host/invest/:region?type=Chemical - region 국가의 회사 중 화학 종목의 주식 정보만 반환
• http://host/characters?class=warrior&upperLevel=30&upperGold=100000 - 캐릭터 중 전사 계열, 30레벨 이상, 100,000 이상의 골드를 소유한 캐릭터만 반환

3. 정리

• 여러개의 query를 API 서버에 존재하는 query 중 선택적으로 사용 가능하고, 만약 API 서버에 query가 없더라도 일반적으로 오류를 반환하지 않습니다.
• param과 query를 적절하게 혼합하여 사용 가능하지만, query는 url의 맨 끝에 위치해야 합니다.

---

Param VS Query 요약

특징	Param	Query
위치	URL 내에 위치	URL의 끝에 위치
목적	특정 지원 식별	필터링, 자원에 대한 옵션 등
필수 여부	o	x
중복 여부	URL 내에서 여러개의 파라미터 사용 가능	여러개의 쿼리 파라미터 사용 가능

공통 특징

• 일반적으로 브라우저 정책에 따라 URL의 길이가 제한이 있지만, curl, axios, fetch 등을 이용해 호출하는 경우 URL 길이 제한이 없습니다.
• http 프로토콜 특성상 클라이언트가 서버로 보내는 URL의 모든 정보는 텍스트 형식이기 때문에 API 서버에서 type validation이 필요합니다.