4강. URL, Path Parameter, Query Parameter

?1. 이번 강의에서 해결할 문제

게임 기록·랭킹 API를 테스트하면서 리소스 식별용 Path Parameter와 조회 조건용 Query Parameter를 구분하는 문제를 해결합니다. 수동으로 한 번 성공하는 데서 끝내지 않고 같은 결과를 다시 확인할 수 있는 요청으로 남깁니다.

✓2. 학습 목표

✓이 강의를 마치면

• 이번 주제의 HTTP 계약을 설명할 수 있습니다.
• Postman에서 성공과 실패 요청을 각각 구성할 수 있습니다.
• PowerShell에서 핵심 요청을 재현하고 결과를 판정할 수 있습니다.

◇3. 핵심 개념

URL의 /players/7에서 7은 특정 리소스를 가리키는 Path Parameter입니다. /rankings?season=2026&limit=10의 season과 limit은 결과를 필터링하거나 표현 범위를 조절하는 Query Parameter입니다. Postman의 Params 탭은 쿼리 문자열을 안전하게 인코딩하고 활성 여부를 한눈에 보여 줍니다.

✎4. 단계별 실습

실습 경로: C:\dev\game-ranking-api-tests

1. Postman에서 GET {{baseUrl}}/players/1을 저장합니다.
2. GET {{baseUrl}}/rankings 요청의 Params 탭에 season=2026, limit=10을 추가합니다.
3. 체크박스를 끄고 URL과 결과가 어떻게 바뀌는지 비교합니다.

PowerShell

$baseUrl = "http://127.0.0.1:8000"
Invoke-RestMethod -Uri "$baseUrl/players/1"
Invoke-RestMethod -Uri "$baseUrl/rankings?season=2026&limit=10"

Postman의 버튼·탭 이름은 버전에 따라 달라질 수 있습니다. 메뉴가 다르면 설치된 앱의 도움말과 Postman 공식 문서를 먼저 확인합니다.

→5. 요청과 응답이 동작하는 이유

라우터는 경로 패턴으로 대상 플레이어를 선택하고 쿼리 값으로 결과 집합을 좁힙니다. 쿼리 매개변수를 빼도 기본 조회가 가능하도록 설계할 수 있지만 필수 Path Parameter를 빼면 다른 경로가 됩니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: Path와 Query 용도를 뒤섞음 해결: 정체성은 경로, 선택 조건은 쿼리로 표현합니다.
• 실수: 공백·한글을 직접 이어 붙임 해결: Postman Params 탭 또는 URI 인코딩 기능을 사용합니다.
• 실수: 숫자 범위를 무시함 해결: 0, 음수, 매우 큰 limit도 실패 사례로 검증합니다.

✎7. 직접 실습

✎직접 실습

1. 존재하는 플레이어와 없는 플레이어를 각각 조회합니다.
2. limit=1과 limit=100 결과 개수를 비교합니다.
3. 지원하지 않는 season 값을 보내 API 동작을 기록합니다.

완료 후 Postman 요청을 저장하고, 실제 API Key·JWT·비밀번호가 이름·본문·스크립트·export 파일에 없는지 확인합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 특정 플레이어 ID는 왜 Path Parameter가 자연스러운가요?
2. 페이지 크기는 왜 Query Parameter가 적합한가요?
3. 쿼리 값의 타입 검증은 어디에서 일어나나요?

■9. 핵심 요약

■핵심 요약

Path Parameter는 리소스를 식별하고 Query Parameter는 조회 방식을 조절합니다. 정상값뿐 아니라 경계값과 잘못된 값도 함께 저장합니다.