API에서 쿼리 파라미터(Query Parameter)란?

API를 다루다 보면 자주 접하게 되는 개념 중 하나가 바로 쿼리 파라미터(Query Parameter)입니다. 처음에는 단순한 옵션처럼 보이지만, 실제로는 API 설계와 데이터 처리의 유연성과 성능을 좌우하는 매우 중요한 요소입니다. 이 글에서는 쿼리 파라미터에 대한 개념부터 동작 원리, 실무 적용까지 이론적이고 구체적으로, 그리고 예제를 통해 직관적으로 설명드리겠습니다.

1. 쿼리 파라미터란?

쿼리 파라미터는 HTTP 요청의 URL 뒤에 key=value 형태로 붙어 있는 데이터입니다. 클라이언트가 서버에 추가적인 조건이나 옵션을 전달하고 싶을 때 사용합니다. 특히 GET 요청에서 자주 활용되며, 서버에 있는 데이터를 "조회"하거나 "필터링"할 때 매우 유용합니다.

예를 들어, 다음과 같은 URL을 보겠습니다:

GET <https://api.example.com/v1/books?author=김영하&sort=latest&page=2>

이 요청에서 author, sort, page는 각각 쿼리 파라미터입니다. 이들을 통해 클라이언트는 "김영하의 책 중 최신순으로 정렬된 결과의 2페이지를 주세요"라는 요청을 표현한 것입니다.

2. URL 구조에서의 쿼리 파라미터 위치

URL은 아래와 같은 구성 요소로 나뉩니다:

프로토콜://도메인/경로?쿼리파라미터#프래그먼트

예:

<https://api.example.com/v1/users?limit=20&offset=40#top>

? 뒤가 쿼리 문자열(Query String)
& 기호로 여러 쿼리 파라미터 연결
#top은 해시(프래그먼트)로, 브라우저에서만 사용되며 서버에는 전달되지 않음

3. 쿼리 파라미터의 주요 사용 목적

목적 설명

필터링(Filter)	특정 조건에 맞는 데이터만 가져오기 (?subject=ENG)
정렬(Sort)	정렬 기준 설정 (?sort=popular)
페이지네이션(Pagination)	데이터 나누기 (?page=2&limit=10)
검색(Search)	검색어 전달 (?q=chatgpt)
범위 설정	날짜/시간 등의 범위 지정 (?from=2023-01-01&to=2023-01-31)

예시: 영화 API

GET /movies?genre=thriller&rating_gte=8.5&year=2023&sort=popularity

의미: 스릴러 장르 중 평점 8.5 이상인 2023년 개봉 영화 중 인기순 정렬

4. 다른 전달 방식과 비교

항목 쿼리 파라미터 경로 파라미터(Path) 요청 본문(Body) 헤더(Header)

위치	URL 뒤 ?	URL 내부	HTTP Body	HTTP 헤더
예	?page=1	/users/123	{ "title": "book" }	Authorization: Bearer xxx
주 사용	조회, 필터링	리소스 식별	생성/수정	인증, 메타정보

5. 쿼리 파라미터의 내부 동작 원리

서버는 다음과 같은 방식으로 쿼리 파라미터를 해석합니다:

URL에서 ? 이후 문자열을 추출
& 기준으로 분리 → 각각 key=value 쌍 생성
= 기준으로 나누어 키-값 매핑
이 정보를 딕셔너리나 맵 자료구조로 내부 처리

예: ?subject=ENG&sort=popular

{
  "subject": "ENG",
  "sort": "popular"
}

서버 언어나 프레임워크에 따라 자동으로 파싱되어 사용됩니다.

6. Spring Boot 예시

@GetMapping("/v1/lectures")
public List<LectureDTO> getLectures(
    @RequestParam(required = false) String subject,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(defaultValue = "popular") String sort
) {
    return lectureService.fetchLectures(subject, page, sort);
}

요청 URL:

GET /v1/lectures?subject=MATH&page=2&sort=latest

자동으로 각 파라미터가 메서드 인자로 주입됩니다.

7. 실무에서의 고려 사항

✅ URL 인코딩 필수

한글, 공백, 특수문자는 반드시 URL 인코딩 필요
예: 김영하 → %EA%B9%80%EC%98%81%ED%95%98

✅ 길이 제한 고려

브라우저나 서버마다 URL 길이 제한 존재 (보통 2,000자 내외)
긴 데이터를 전달하려면 POST 방식 + Body 사용 고려

✅ 민감정보 금지

쿼리 파라미터는 URL에 노출되므로 비밀번호, 토큰 등은 절대 포함 금지

✅ 기본값 설정 권장

서버에서 디폴트 값 설정하여 클라이언트가 파라미터를 생략해도 동작 가능하도록 설계

8. Swagger / OpenAPI 문서에서의 정의

쿼리 파라미터는 OpenAPI에서 다음과 같이 명시됩니다:

parameters:
  - name: subject
    in: query
    description: 강의 과목
    required: false
    schema:
      type: string

이 정의를 기반으로 Swagger UI에서 자동 문서화 및 테스트 지원이 됩니다.

9. 마무리 요약

항목 설명

형식	?key=value&key2=value2
위치	URL의 끝 부분
주 목적	조회, 필터링, 검색, 정렬, 페이징 등
장점	직관적이고 캐시 가능, 즐겨찾기 가능
단점	민감정보 금지, 길이 제한 있음

✅ 참고로 알아두면 좋은 점

GET 요청만 쿼리 파라미터를 쓰는 것은 아님. DELETE, HEAD, OPTIONS에서도 사용 가능
POST 요청에서도 URL에 쿼리 파라미터를 붙이는 것이 가능하지만, 일반적이지는 않음

🔚 마치며

쿼리 파라미터는 단순한 key-value 쌍 그 이상입니다. API 사용성을 높이고, 프론트-백 간 유연한 통신을 가능하게 하는 중요한 도구입니다. 설계와 구현, 문서화까지 신중하게 다뤄야 할 요소입니다.

Software