Query String, Query Params, @RequestParam은 어떻게 다른거지?
API 명세서를 작성하던 중 포스트맨의 Query-Params와 web 개념 상의 Qeury-Stirng, Request-Param, Spring Annotation @RequestParam, @PathVariable 사이의 관계에 대해 명확히 알고 싶어져서 개념의 상하관계를 정립하고 정의해두기 위해서 공부한 내용을 작성하고자 한다.
단어를 혼용해서 쓰는 경우가 많고 워낙 비슷한 느낌이라 헷갈리는 web 개념, 스프링 어노테이션 등의 다음의 용어들을 정리해본다. 이 포스팅에서는 개념들간의 상하관계와 간단한 정의만 서술하고 자세한 내용들은 추후에 이어질 포스팅에 업로드할 예정이다.
web 개념에서의 상위 레벨부터 알아보자
간단히 각 개념의 레벨을 설명하자면 REST API 파라미터 타입 -> Reqeust 객체가 가지는 method -> 서버단에서 부르는 이름 -> Spring Annotation 과 같다.
우선 우리가 다룰 키워드들의 가장 상위 개념은 REST API 파라미터 타입이다. API parameter는 resource, 즉 클라이언트로부터 받는 request에 대해 수행할 작업 유형을 결정하는 가변적인 부분을 일컫는다. REST API를 구축하고자 할 때마다 API 엔드포인트에 어떤 파라미터가 존재해야 하는지 결정해야 하며 API 파라미터는 response에 영향을 미치기 위해 엔드포인트와 함께 전달할 수 있는 옵션이라고 이해하면 된다. 해당 포스팅에서는 키워드와 관련 있는 Path Parameters, Query Parameters, Body Parameters만 언급하고 넘어가도록 하겠다.
REST API Parameter Type이 더 궁금한 사람은 여기로!
그 다음 단계로 내려오는 개념은 Request object의 method이다. Reqeust 객체는 API를 컨트롤하기 위한 메소드로 param, query, body. 이 세 가지를 담고 있다. REST API 파라미터로 지정된 타입에 따라 Request odject의 method가 달라진다.
Path Parameters > Request Param > Path Variable > @PathVariable
Path Parameters는 엔드포인트의 일부이며 요청 경로를 매개변수화하는데에 사용된다. 지정된 옵션의 값으로 채워진 placeholder를 추가한다.
board/{boardId}/center/{centerId} // {boradId}와 {centerId}에 아래와 같이 값이 들어간다board/123/center/456 // boardId가 123인 게시판과 centerId가 456인 시설을 가져온다이 경우에, 123과 456을 서버단에 전달한다.
따라서 reqeust param은 uri에 포함된 변수를 담는다. 위와 같은 경우에서는 123을 centerId에 담는 것이다.
이때 서버단에서는 request param을 Path Variable로 칭한다.
Path Variable 형태로 매개변수를 넘겨 받고자 할 때 Spring의 경우 Controller단에서 @PathVariable 어노테이션을 사용한다.
Query Parameters > Request Query > Query Parameter > @RequestParam
Query Parameters는 가장 일반적인 매개 변수 유형으로, 물음표(?) 뒤에 있는 URL 끝에 지정된다. 이때 ?뒤에 오는 매개변수와 그 값들을 Query String이라고 부른다. 쿼리 스트링에서는 각 매개변수를 &로 구분하여 차례로 나열한다.
board/center?boardId={boardId}¢er={centerId}board/center?boardId=123¢erId=456위와 같은 경우에는 query parameter type으로 request를 넘기는 것이며 ?boardId={boardId}¢er={centerId} 이 부분이 Query String이라고 볼 수 있겠다.
또한 Reqeust object 관점에서 보자면 request objectd의 method는 request qeury를 담고 있는 것이고 주소 바깥, ? 이후의 변수를 담는다.
이때 서버단에서는 request query를 Query Parameter로 칭한다.
Query Parameter 형태로 매개변수를 넘겨 받고자 할 때 Spring의 경우 Controller단에서 @RequestParam 어노테이션을 사용한다.
헷갈리는 부분은 여기까지이고 Body Parameters type을 채택한 경우 request object는 reqeust body로 method를 가지고 Spring에서는 @ReqeustBody 어노테이션을 사용한다.
결론
REST API parameter type과 request object method 등 정확히 알지 못했던 web 지식을 공부하며 혼동하여 사용하고 있었던 개념들을 정리하였고 이를 바탕으로 API 명세서를 작성할 때 uri에 들어가는 변수들을 Path-Variable과 Query-String으로 분류하여 적기로 결정했다.
