[API] Path Parameter & Query Parameter에 대해서

1. Path Parameter란 ? 

URL로는 고유한 자원(resource, data)을 지칭할 수 있다. 

• http://naver.com/stocks
• http://google.com/mail

등을 보면 알 수 있다. 그러나 특정 자원을 가리키는 url 경로에 가변적인 부분이 있다면 http://naver.com/stocks/kakao 라는 주소는 직관적으로 카카오사의 주식 정보를 나타냄을 알 수 있습니다. 이 상황에 회사의 이름 부분은 다른 회사에 대한 정보를 요청할 때에는 언제든 바뀔 수 있는 가변적 자리입니다. 즉, 변수로 지정해 둘 수 있다는 의미가 되며 이 변수의 이름을 Path Parameter라고 부릅니다. 

아래 예시와 같이 특정 path parameter가 변경되며 백엔드 서버에서는 http://naver.com/stocks/:companyName 등과 같은 형태로 라우팅 할 수 있습니다. 

• http://naver.com/stocks → http://naver.com/stocks/uber

변수로 지정해도 '특정 리소스를 가리키는' URI로서의 역할은 변하지 않습니다. 백엔드 서버 입장에서는 매개변수지만, 클라이언트가 API를 호출할 경우 해당 매개변수를 실제 값으로 대체해 호출하게 됩니다. 해당 변수는 유일한 값을 식별하는 역할을 합니다. 

 

제품 데이터 목록을 호출할 때와 Path parameter를 이용해 한 가지의 제품 데이터만 호출했을 때 url은 제품 정보를 나타낸다는 점에서 비슷해 보일 수 있지만, 서로 다른 정보를 요청하는 API입니다. 이와 같이 서로 다른 데이터지만 resource(자원)의 종류는 동일할 경우 path parameter를 이용해 RESTful 한 API를 구성할 수 있습니다. 

 

[GET] 메소드에서 뿐 아니라 path parameter는 모든 메소드에서 사용할 수 있습니다. 

[POST] 메소드는 데이터를 저장할 때 사용되어 특정한 변수가 없어도 됩니다. 

[PATCH] 메소드는 특정 리소스를 지칭해 '수정할 것'을 표현하므로 path parameter로 어떤 데이터를 수정할지 알려줄 수 있습니다. 

[DELETE] 메소드 또한 마찬가지로 특정한 리소스를 지칭해 '어떤 제품을 삭제할지'를 명확히 가리킬 수 있습니다. 

 

2. Query Parameter란 ?

Query parameter는 url에서 특정 조건을 주고 싶을 때 사용하는 매개변수 유형입니다. 

같은 API를 호출한다고 해도, 서로 다른 조건으로 나열하는 것이 필요한 상황에 사용합니다. URL끝에 물음표(?) 뒤에 나타나며, and 기호(&)로 구분된 이름 = 값 쌍으로 구성되어 있습니다. 

같은 상품 목록 데이터를 호출할 때, 신상품 순, 낮은 가격순 등 데이터를 호출하는 API를 매번 새로 생성하는 것은 비효율 적입니다. 따라서 필요한 조건을 요청에 따라 선택적으로 처리할 수 있는 통일한 API를 구성할 때 사용합니다. 

 

Query parameter는 HTTP의 [GET], [DELETE] 요청에서만 사용하고, 유일 값을 식별하기 위한 용도가 아닌 옵션을 줄 때 사용합니다. (ex. 검색, 데이터 정렬, 데이터 필터링...)

 

1️⃣ 필터링

[GET] 메서드로 제품의 목록을 표현하는 상황에도 다양한 방식으로 데이터를 전송합니다. 

url에서 쿼리 파라미터를 이어 나열할 때, & 연산자 (and 연산자)를 사용합니다. &는 파라미터를 나열하기 위해 사용되는 여난자로, 필터링 조건이 늘 and 조건이라는 뜻은 아닙니다. API를 어떻게 작성하느냐에 따라 or 조건으로 이용될 수 있고 url의 & 연산자와 API의 동작 방식은 독립적입니다. 

 

예시 

🔵 GET / products?price>=2000 → 가격이 2000원보다 크거나 같은 제품을 모두 필터링 

🔵 GET /products?price <10000&name=텀블러 → 가격이 10000원 이하 그리고 이름이 '텀블러'인 제품 필터링

 

2️⃣ 정렬

동일한 데이터라도 신상품순, 낮은 가격, 높은 가격 순으로 정렬해야 할 때가 있습니다. 

 

🔵 GET /products?ordering=-id → 데이터를 id 역순으로 정렬하는 사용 예시

 

3️⃣ 데이터 수 조절(Pagination)

데이터베이스에 저장된 데이터의 수가 엄청나게 많다면, 클라이언트가 한 번에 모든 데이터를 호출해 사용하면 통신 속도가 매우 저하될 수 있어 비효율적입니다. 한 번 클릭에 정해진 수만큼의 데이터만 호출하는 것이 효율적이며 이런 상황에 필요한 데이터의 시작점, 마지막 끝나는 점을 쿼리 스트링을 통해 전달할 수 있습니다. 

관습적으로 데이터의 시작점을 offset, 주고받고자 하는 데이터의 개수를 limit으로 칭합니다. 

 

🔵 GET /products?offset=0&limit=50 → 데이터의 개수를 0부터 50까지 제한해 호출하는 사용 예시 

 

4️⃣ 검색

검색은 독립적인 새로운 기능처럼 보이지만, 필터링과 동일한 기능입니다. 특정 키워드를 기준으로 필터링하며 통상적으로 search라는 단어를 주로 사용하지만, 검색어를 이용하는 기준이 늘 동일해야 하는 것은 아닙니다. 

 

🔵 GET /products?search=텀블러 → products 데이터를 특정 키워드로 검색하기 위한 사용 예시

 

Query parameter를 이용해 예시로 생성된 위 4가지 API는 기본적으로 [GET] /products와 동일한 API를 호출하는 것입니다. 따라서 API는 한 가지이지만 쿼리파라미터를 변수로 받아 각각의 조건마다 필요한 데이터를 전송할 수 있습니다. 

 

위 변수들을 request body에 넣어 요청할 수 없나라고 생각할 수 있지만 데이터를 표현하는 HTTP method는 GET이고, GET method에서는 request body를 사용하지 않는 것이 권장됩니다. 따라서 GET method를 호출하면서 동시 정보를 전달할 경우 Query parameter를 이용해야 합니다. 

 

쿼리 매개변수라고도 불리는 Query parameter를 서버 코드에서 다룰 때는 클라이언트에서 값을 주지 않을 경우 대비해 기본값을 설정할 수 있습니다. 그리고 동일한 키 값으로 여러 값을 전달할 경우, 서버에서 배열로 값을 받을 수 있습니다.