경로 매개변수 (Path Parameters):
경로 매개변수는 URL의 일부로서, 특정 리소스나 리소스 그룹을 식별하는 데 사용됩니다.
이는 주로 리소스의 고유 식별자(ID)를 지정할 때 사용됩니다.
예: /payments/:paymentId는 특정 결제 리소스를 식별합니다.
쿼리 매개변수 (Query Parameters):
쿼리 매개변수는 URL의 ? 뒤에 위치하며, 추가 정보를 제공하거나 리소스를 필터링, 정렬, 페이지네이션하는 데 사용됩니다.
이들은 선택적이며, API의 기능을 미세 조정하는 데 사용됩니다.
예: /payments?academyId=1234는 모든 결제 중 특정 학원에 속하는 결제들을 필터링합니다.
필터 옵션 vs 경로 매개변수
필터 옵션과 경로 매개변수의 주된 차이는 필수성과 목적에 있습니다:
필수성: 경로 매개변수는 필수적입니다. 즉, 해당 매개변수 없이는 URL이 완전하지 않고 해당 리소스에 접근할 수 없습니다. 반면, 쿼리 매개변수는 선택적입니다. 이들 없이도 기본적인 API 기능은 작동합니다.
목적: 경로 매개변수는 특정 리소스를 식별하는 데 직접적으로 사용됩니다. 예를 들어, /payments/:paymentId에서 :paymentId는 특정 결제를 식별합니다. 쿼리 매개변수는 보다 광범위한 리소스 셋을 필터링하거나 정렬하는 등의 추가적인 기능을 제공합니다.
예시
/payments/:id의 경우, 일반적으로 :id는 특정 결제의 고유 ID로 해석됩니다. 즉, 이 URL은 "ID가 :id인 결제의 상세 정보를 가져온다"로 이해됩니다.
/payments?academyId=1234의 경우, 이 URL은 "모든 결제 중 academyId가 1234인 결제를 필터링한다"로 해석됩니다. 여기서 academyId는 선택적 필터로, 결제 리소스의 하위 집합을 선택하는 데 사용됩니다.
결국, API의 명확성과 사용자의 이해도를 높이기 위해서는, 경로 매개변수를 주로 리소스의 식별자로, 쿼리 매개변수를 필터링이나 추가 옵션 제공에 사용하는 것이 좋습니다.
