[Web] Path Variable VS Query Parameter

백앤드 개발을 하다보면 API의 endpoint를 어떻게 설계할지에 대한 고민을 계속 하게 됩니다.

저 역시 그런 생각을 하다가 GET method를 통해 데이터를 넘길 경우에 Path Variable와 Query Parameter 중 뭐가 더 적합한가에 대한 의구심을 품게 되었고 이를 찾아보고 정리하게 되었습니다.

각각에 대해 알아보며 어느 상황에 쓰는게 적합할지 생각해봅시다.

 

Path Variable

Path Variable 는 이름에서도 알 수 있듯이 경로를 변수로서 사용합니다.

게시물이 존재하며 각각의 게시물을 볼 수 있는 경우를 생각해봅시다.

각각의 게시물을 보기 위해서는 게시물의 id를 서버에 넘겨줘야 합니다.

이를 Path Variable 를 사용하면 다음과 같이 나타냅니다.

/post/6

 

Query Parameter

Query Parameter 은 경로 뒤에 입력 데이터를 함께 제공하는 식으로 사용합니다.

바로 예시부터 살펴봅시다.

/post?post_id=6

이 때 ? 이후의 부분을 query string이라고 하며 뒤는 key, value의 쌍으로 이루어집니다.

다음과 같이 &로 연결하여 여러 개의 데이터를 넘길 수도 있습니다.

/post?post_id=6&key1=value1

 

 

Path Variable VS Query Parameter

어느 상황에 어떤 방식을 써야하는지 생각을 해봅시다.

우선 위의 예시처럼 어떤 resource를 식별해야하는 상황을 생각해보겠습니다.

서버에서는 어느 방식으로 넘어오던지 간에 받아온 resource의 id로 쿼리를 날리게 됩니다.

그런데 만약 존재하지 않은 resource의 id가 들어올 경우 각각 어떻게 동작할까요?

우선 Path Variable 은 저 경로의 존재하는 페이지가 없으므로 404 에러를 발생합니다.

그에 비해 Query Parameter는 서버로 데이터가 넘어가고 쿼리를 날리며 해당하는 데이터가 없을 경우 따로 에러 핸들링을 해줘야합니다.

즉 resource를 식별해야하는 상황에서는 Path Variable 가 더 적합합니다.

 

이번에는 정렬이나 필터링을 해야할 상황을 생각해보겠습니다.

post에 대해 django 관련 글만 필터링하는 아래와 같은 예시가 있습니다.

post/django
post?category=django

django 관련 글이 없을 경우, Path Variable 는 404에러를 발생하고 Query Parameter 는 빈 리스트를 반환할 것입니다.

펄터링을 하다가 404에러가 발생하는 것은 부적절하므로 정렬이나 필터링을 해야하는 상황에서는 Query Parameter 가 더 적합합니다.

 

 

마무리

사실 API를 설계하는데 있어서 정답은 없다고 생각합니다.

특정 서비스에서는 필터링에 실패할 경우 404에러를 띄우는게 더 적합할 수 도 있습니다.

다만 위에서 든 예시가 best practice이고 이를 지키는 것은 다른 개발자와의 협업, 유지 보수 측면에서도 더 효과적이라고 생각합니다.