rest api 쿼리 스트링 vs path variable 선택하는 기준?

안녕하세요! REST API 는 표준화된 규격이 아니다보니 구현하는곳마다 조금씩 다를수는 있습니다만, 저의 경우 path variable 에 명시하는 값은 resource 를 명확하게 구분하는 값(pk)을, query parameter 는 optional 로 지원되야하는 파라미터일 경우 사용하고 있습니다. 고객(Customer)과 고객의 주문(Order)과 관련된 REST API 를 만들어보는것을 예로 들어 설명해보겠습니다. 이때 정의되는 리소스는 크게 다음과 같습니다. - 고객: customer - 주문: order 고객과 주문의 관계는 1:N 관계가 될것이고 주문은 고객의 리소스 하위에 소속이 되는 구조로 정의가 되야할것입니다. 따라서 고객과 주문과 관련된 REST API 를 정의해보면 다음과 같이 정의할 수 있습니다. - 고객 리스트 조회: /api/v1/customers - 고객 정보 조회: /api/v1/customers/{customerId} - 고객의 주문 리스트 조회: /api/v1/customers/{customerId}/orders - 고객의 주문 조회: /api/v1/customers/{customerId}/orders/{orderId} 여기서 고객 리스트 조회나 고객의 주문 리스트 조회 API 의 경우 다음과 같은 스펙이 있을 수 있습니다. - 고객의 리스트를 조회할 때 이름순으로 조회하고 싶다. - 고객의 주문 리스트를 조회할 때 paging 처리를 하고 싶다. 위와 같은 기능은 상황에 따라 optional 하게 동작하게 해야하므로 optional 파라미터를 정의해야할텐데요 이러한 파라미터를 query 파라미터로 정의하면 대응하기 용이합니다. - /api/v1/customers?orderBy=name&sort=desc - /api/v1/customers/{customerId}/orders?page=1&pageSize=100 제가 설명드린 예시는 Resource 간의 관계가 명확하고 GET Method 에 한해 말씀드린것이긴 합니다만, 다음과 같은 상황도 있을 수 있습니다. - 고객의 주문 리스트 중에 "책" 주문 리스트를 조회하고 싶다. 이럴 경우 크게 두가지 형태를 고민해볼 수 있습니다. - /api/v1/customers/{customerId}/orders?type=book - /api/v1/customers/{customerId}/book-orders(혹은 /api/v1/customers/{customerId}/orders/book) 앞서 말씀드렸다시피 REST API 는 표준화된 규격이 아니다보니 구현하는 사람 마음대로 구현할 수 있습니다. 즉, 정답은 없고 둘중에 무얼 하든 할 수 있습니다. 다만 저의 기준으로 구현을 해본다면 만약 "책"과 다른 type 에 대한 order 리소스의 형태가 다르다면 path variable 을 다르게 하여 resource 를 명확하게 구분하는 방향으로 할것 같고요, 그게 아니라면 query parameter 로 대응할것 같습니다. 질문하신 필터링 기능이 왠지 위와같은 상황이시지 않을까 싶어 말씀드렸는데요, 저의 작은 의견이 부디 도움이 되시길 바라겠습니다. 추가로 REST API 설계와 관련된 좋은 글을 참고삼아 공유 드립니다. - https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design - https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-implementation

흠 .. 일단 데이터를 가지고 온다 는 Get 메서드 그리고 필터링 부분은 쿼리 스트링으로 가지고 오는데요. 여기서 중요한 것은 제가 알기로는 정답은 없습니다. 팀마다 차이가 있고 도메인 마다 차이가 있어서, 그 부분에 있어서 규칙성 만 있으면 된다라고 생각 드네요!!! rest규칙을 지켜서...? 만들면 될거 같습니다!!!