[API] Path parameter VS Query Parameter (기록용)

juno·2022년 8월 17일
1

통신

목록 보기
2/4

Path Parameter

1. path parameter란?

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

등을 보면 알 수 있죠. 그러나 특정 자원을 가리키는 url 경로에 가변적인 부분이 있다면 어떻게 될까요?

http://naver.com/stocks/kakao 라는 주소는 직관적으로 kakao사의 주식 정보를 나타냄을 알 수 있습니다. 이 상황에서 회사의 이름 부분은 다른 회사에 대한 정보를 요청할 때에는 언제든지 바뀔 수 있는 가변적인 자리입니다.

등으로 가리키는 특정 리소스가 변경될 수 있죠. 즉, 변수로 지정해둘 수 있다는 의미가 됩니다. 이 변수의 이름을 Path Parameter 라고 부릅니다. 백엔드 서버에서는 http://naver.com/stocks/:companyName 이와 같은 형태로 라우팅 할 수 있습니다.

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

아래에서 제품 데이터를 목록으로 호출했을 때와, Path parameter를 이용해 한가지의 제품에 대한 데이터만을 호출했을 때의 차이점을 확인할 수 있습니다. 두 url은 제품 정보를 나타낸다는 점에서 비슷해보일 수 있지만, 엄연히 서로 다른 정보를 요청하는 서로 다른 API 입니다.

  • 제품의 목록 데이터 : products 라는 리소스에 접근. 제품의 전체 목록을 나타냄.

  • 제품의 상세 데이터 : procuts/1 라는 1번 리소스에 접근. 1번 제품에 대한 정보만을 나타냄.

[GET] 메소드에서 뿐만 아니라 path parameter는 모든 메소드에서 사용할 수 있습니다. [POST] 메소드는 데이터를 저장할 때 사용되므로, 특정한 변수가 없어도 됩니다. 즉 path parameter가 사용되지 않을 수도 있습니다. [PATCH] 메소드는 특정 리소스를 지칭하여 ‘수정할 것'을 표현하므로 path parameter로 어떤 데이터를 수정할 지 알려줄 수 있습니다.

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

2. 실제 사용 예시

네이버 지도에서는 각 장소마다 상세한 정보를 제공합니다. 장소마다 고유한 URI를 부여하고, 특정 자원에 접근할 수 있도록 만들어 두었습니다.

https://map.naver.com/v5/entry/place/:placeId

이와 같이 서로 다른 데이터지만 resource(자원)의 종류는 동일할 때, path parameter를 이용하여 RESTful한 API를 구성할 수 있습니다

Query Parameter

1. query parameter란?

Query parameter는 url에서 특정한 조건을 주고싶을 때 사용하는 매개변수 유형입니다. 같은 API를 호출한다고 해도, 서로 다른 조건으로 나열하는 것이 필요한 상황에 사용합니다. URL 끝에 물음표(?) 뒤에 나타나며, and 기호(&)로 구분된 이름=값 쌍으로 구성되어 있습니다.

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

쿼리 파라미터는 HTTP의 [GET], [DELETE] 요청에서만 사용하고, 유일 값을 식별하기 위한 용도가 아닌 옵션을 줄 때 사용합니다. 크게 다음과 같은 상황에서 사용합니다.

  • 데이터 필터링
  • 데이터 정렬
  • 데이터 수 조절 (페이지네이션)
  • 검색 등

1-1. 필터링

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

  • 제품 가운데 가격이 3000원인 데이터만을 전송

  • 제품 가운데 가격이 3000원이면서, 동시에 이름이 ‘사과'인 데이터만을 전송

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

1-2. 정렬

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

1-3. 데이터 수 조절 (Pagination)

데이터베이스에 저장된 데이터의 수가 엄청나게 많다면, 클라이언트가 한 번에 모든 데이터를 호출하여 사용하면 통신 속도가 매우 저하될 수 있어 비효율적입니다. 따라서 한 번 클릭에 정해진 수 만큼의 데이터만 호출하는 것이 보다 효율적입니다. 이러한 상황에서 필요한 데이터의 시작점와 마지막 끝나는 점을 쿼리 스트링을 통해 전달할 수 있습니다. 관습적으로 데이터의 시작점을 offset , 주고 받고자 하는 데이터의 갯수를 limit 으로 칭합니다.

아래와 같은 요청을 보내면, 전체 데이터 가운데 0번부터 100번까지만 호출하게 됩니다.

1-4. 검색

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

  • [GET] /products?price=3000

  • [GET] /products?ordering=-id

  • [GET] /products?offset=0&limit=100

  • [GET] /products?serach=홍길동

Query parameter을 이용해 생성된 위 4가지 API는 기본적으로 [GET] /products 와 동일한 API를 호출하는 것입니다. 따라서 API는 한가지이고, query string을 변수로 받아서 각각의 조건마다 필요한 데이터를 전송해야합니다.

위 변수들을 request body 에 넣고 요청할 수 있지 않을까? 라고 생각할 수 있습니다. 데이터를 표현하는 HTTP method는 [GET] 이고, GET method에서는 request body를 사용하지 않는 것이 권장됩니다. 따라서 GET method를 호출하면서 동시에 정보를 전달할 때에는 query parameter를 이용해야합니다.

쿼리 매개변수라고도 불리는 query parameter를 서버 코드에서 다룰 때에는, 클라이언트에서 값을 주지 않을 때를 대비해 기본값을 설정할 수있습니다.

또한, 동일한 키값으로 여러 값을 전달할 경우, 서버에서는 배열로 값을 받을 수 있습니다.

  • [GET] /products?size=230&size=240&size=280 → { size : [230, 240, 280] }

Summary

  • 특정 리소스 정보를 반환하는 API를 설계할 때, 접근하는 고유한 정보를 변수화 하여 지정해둔 매개변수를 path Parameter 라 칭합니다. 해당 변수는 유일한 값을 식별하는 역할을 합니다.

  • 필요한 조건을 요청에 따라 데이터를 선택적으로 처리할 수 있는 통일된 API를 구성할 때 사용하는 매개변수를 query parameter라 칭합니다. 유일 값을 식별하기 위한 용도가 아닌 옵션을 줄 때 사용합니다.

  • Query parameter는 필터링, 정렬, 페이지네이션, 검색등의 경우에서 활용합니다.

profile
안녕하세요 인터랙션한 웹 개발을 지향하는 프론트엔드 개발자 입니다. https://kimjunho97.tistory.com => 블로그 이전 중

1개의 댓글

comment-user-thumbnail
2023년 12월 4일

감사합니다. 잘 읽고 갑니다

답글 달기