쿼리 파라미터와 경로 파라미터의 차이점과 활용법

BE 테스트케이스 작성 시, 게시글을 참고 하시면

많은 도움이 될 것 같습니다.

 

 

쿼리 파라미터(Query Parameters) vs 경로 파라미터(Path Parameters)

- HTTP 요청에서의 차이

 

API 설계에서 파라미터를 전달하는 방식은 매우 중요합니다. 클라이언트와 서버 간의 데이터 전송 방식은 API의 사용성과 직결되기 때문입니다. HTTP 요청에서 파라미터를 전달하는 방법에는 **쿼리 파라미터(Query Parameters)**와 **경로 파라미터(Path Parameters)**가 있으며, 두 방식은 각각 다른 방식으로 정보를 전달합니다. 본 글에서는 이 두 가지 방식의 차이점과 그 사용 사례를 알아보겠습니다.

 

1. 쿼리 파라미터(Query Parameters)

쿼리 파라미터는 URL의 쿼리 스트링 부분에 포함되어 전달됩니다. URL 뒤에 ?를 사용하여 여러 파라미터를 &로 구분하며, key=value 형식으로 데이터를 전달합니다.

예시:

GET /api/program-search?batchProgramNo=123&batchProgramExplainContent=test&orderByKey=name

 

위와 같은 요청에서 batchProgramNo, batchProgramExplainContent, orderByKey는 쿼리 파라미터입니다. 이 방식은 데이터의 개수와 종류에 관계없이 여러 파라미터를 URL에 쉽게 추가할 수 있어 유용합니다.

 

 

• 장점:
  • 여러 파라미터를 한번에 전송할 수 있습니다.
  • URL에서 파라미터를 쉽게 확인할 수 있습니다.
  • 쿼리 파라미터는 선택적인 경우가 많아, 일부만 전달해도 됩니다.
• 단점:
  • URL이 길어질 수 있습니다.
  • 검색, 필터링 등의 요청에 자주 사용되며, 이를 잘못 사용하면 URL이 복잡해질 수 있습니다.

쿼리 파라미터는 검색 조건이나 필터링, 정렬 옵션 등 동적으로 요청을 처리할 때 유용합니다. 예를 들어, 데이터베이스에서 검색 결과를 정렬하거나 필터링하는 경우에 자주 사용됩니다.

 

 

 

반응형

 

 

 

2. 경로 파라미터(Path Parameters)

경로 파라미터는 URL 경로 내에 포함된 변수를 의미합니다. URL 구조에서 {parameter} 형태로 사용되어, 경로 자체가 의미를 가지게 됩니다. 이러한 방식은 보통 RESTful API에서 리소스를 명확히 식별하거나, 특정 리소스를 조회할 때 사용됩니다.

예시:

GET /api/program-search/123/test/name

위의 URL에서 123, test, name은 경로 파라미터입니다. 경로 파라미터는 URL 경로 내에서 값을 받으며, 보통 고유한 식별자나 리소스의 상태를 나타내는 데 사용됩니다.

• 장점:
  • URL이 간결하고 명확합니다.
  • RESTful API 설계에서 리소스를 잘 나타내는 방식입니다.
  • 데이터를 요청하는 방식이 직관적이며, 리소스의 위치를 명확히 식별할 수 있습니다.
• 단점:
  • 동적인 데이터를 많이 처리할 때는 쿼리 파라미터보다 유연성이 떨어질 수 있습니다.
  • 경로 자체가 변경되면 API의 엔드포인트가 변경되므로, 버전 관리가 중요할 수 있습니다.

경로 파라미터는 주로 고유한 리소스를 식별할 때 사용됩니다. 예를 들어, 특정 프로그램의 정보를 조회하거나, 특정 데이터를 수정하는 API에서 활용됩니다.

 

 

 

 

 

 

3. 차이점 정리

queryParameters와 pathParameters는 서로 다른 위치에서 파라미터를 전달하는 방식입니다.

• **queryParameters**는 URL의 쿼리 스트링에 포함되어 파라미터를 전달합니다. 예를 들어, GET /api/program-search?batchProgramNo=123&orderByKey=name와 같은 형식입니다.
• **pathParameters**는 URL의 경로 부분에 포함되어 파라미터를 전달합니다. 예를 들어, GET /api/program-search/123/name과 같은 형식입니다.

둘의 주요 차이는 쿼리 파라미터는 필터링, 정렬 등의 부가적인 정보를 담고, 경로 파라미터는 고유한 리소스 식별자나 핵심적인 정보를 전달하는 데 사용된다는 점입니다.

 

4. 실제 적용 사례

실제 프로젝트에서는 두 가지 방법을 혼합하여 사용하기도 합니다. 예를 들어, 다음과 같이 쿼리 파라미터와 경로 파라미터를 동시에 사용하는 경우도 있습니다:

GET /api/program-search/123?batchProgramExplainContent=test&orderByKey=name

여기서 123은 경로 파라미터로 특정 프로그램을 식별하고, batchProgramExplainContent, orderByKey는 쿼리 파라미터로 해당 프로그램의 검색 및 정렬 옵션을 정의하는 방식입니다.

이렇게 두 가지 방법을 조합함으로써 API의 유연성과 직관성을 높일 수 있습니다.

 

결론

쿼리 파라미터와 경로 파라미터는 각각의 용도와 목적에 맞게 사용되어야 합니다. 쿼리 파라미터는 주로 검색, 필터링, 정렬 등 다양한 옵션을 제공하는 데 적합하며, 경로 파라미터는 리소스 식별자나 고유한 데이터를 다룰 때 유용합니다. 올바른 파라미터 사용은 API의 직관성, 유연성, 확장성 등을 높이는 중요한 요소이므로, 상황에 맞게 적절히 선택하여 사용하는 것이 중요합니다.

 

 

테스트케이스 작성 예시)

resultActions.andExpect(status().isOk())
                .andDo(document("test-search",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint()),
                        pathParameters(
                                parameterWithName("testNo").description("테스트 번호"),
                                ~
                        ),
                        responseFields(
                                fieldWithPath("returnCode").type(JsonFieldType.STRING).description("결과 코드"),
                                fieldWithPath("returnMessage").type(JsonFieldType.STRING).description("결과 메세지")                                
                        )
                ))
                .andDo(print())
                .andExpectAll(jsonPath("$.returnCode").value("S"));