2강. HTTP 요청·응답 구조와 상태 코드

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

게임 기록·랭킹 API를 테스트하면서 HTTP 메시지의 메서드·경로·헤더·본문과 상태 코드 계열을 읽습니다. 수동으로 한 번 성공하는 데서 끝내지 않고 같은 결과를 다시 확인할 수 있는 요청으로 남깁니다.

✓2. 학습 목표

✓이 강의를 마치면

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

◇3. 핵심 개념

요청은 메서드, URL, 헤더, 선택적 본문으로 구성되고 응답은 상태 코드, 헤더, 본문으로 구성됩니다. 2xx는 성공, 4xx는 요청 또는 인증 문제, 5xx는 서버 처리 실패를 뜻합니다. 숫자 하나만 보지 말고 오류 JSON의 detail 같은 필드도 함께 확인해야 원인을 좁힐 수 있습니다.

요청과 응답을 구성하는 값

구분	항목	답하는 질문	예
요청	method	무엇을 하려는가	GET
요청	URL/path	어느 서버의 어떤 대상인가	/health
요청	headers	본문 형식·인증 같은 부가 정보는 무엇인가	Accept: application/json
요청	body	서버에 보낼 데이터가 있는가	GET health에는 없음
응답	status	요청을 어떻게 처리했는가	200 OK, 404 Not Found
응답	headers	응답 표현과 캐시 정보는 무엇인가	Content-Type: application/json
응답	body	실제 결과 또는 오류 세부 정보는 무엇인가	{"status":"ok"}

가장 작은 성공·실패 메시지 비교

성공 요청과 응답

GET /health HTTP/1.1
Host: 127.0.0.1:8000

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

없는 경로 요청과 응답

GET /not-found HTTP/1.1
Host: 127.0.0.1:8000

HTTP/1.1 404 Not Found
Content-Type: application/json

{"detail":"Not Found"}

404는 서버에 연결됐지만 해당 method와 path 조합을 찾지 못했다는 뜻입니다. 서버가 꺼져 연결 자체가 실패한 경우에는 HTTP 상태 코드가 도착하지 않습니다. 두 실패를 구분해야 잘못된 경로를 고치면서 서버를 재설치하는 일을 피할 수 있습니다.

✎4. 단계별 실습

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

실행 전 상태: 로컬 API 서버가 127.0.0.1:8000에서 실행되고 /health가 JSON을 반환해야 합니다. 먼저 서버 터미널을 열어 두고 실제 비밀 값 없는 로컬 주소만 사용합니다.

1. 정상 상태 엔드포인트의 응답 헤더까지 저장합니다.
2. 없는 경로로 404를 의도적으로 만듭니다.
3. 성공과 실패의 상태·본문을 표로 비교합니다.

PowerShell

$baseUrl = "http://127.0.0.1:8000"
Invoke-WebRequest -Method Get -Uri "$baseUrl/health" | Select-Object StatusCode, Headers, Content
try { Invoke-RestMethod -Uri "$baseUrl/not-found" } catch { $_.Exception.Response.StatusCode.value__ }

구체적인 성공과 실패 결과 읽기

1. $baseUrl 한 곳에 공통 서버 주소를 저장해 경로만 바꿉니다.
2. Invoke-WebRequest는 상태·헤더·본문을 모두 가진 응답 객체를 반환합니다.
3. Select-Object가 이번 비교에 필요한 세 항목만 화면에 보여 줍니다.
4. PowerShell은 4xx를 예외로 처리하므로 try/catch에서 응답 상태를 읽습니다.
5. 성공 요청은 200과 JSON 본문, 실패 요청은 404와 오류 JSON이 나와야 합니다.

오류 본문도 기록하려면 catch 안에서 $_.ErrorDetails.Message를 확인합니다. PowerShell 버전에 따라 응답 객체 속성이 다를 수 있으므로 상태 접근이 실패하면 $_.Exception.Response | Format-List *로 제공되는 필드를 먼저 봅니다.

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

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

서버는 라우팅 성공 여부와 처리 결과를 상태 코드로 요약합니다. 헤더는 표현 형식과 캐시 같은 메타데이터를 전달하고, JSON 본문은 실제 결과나 오류 세부 정보를 전달합니다.

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

!자주 하는 실수

• 실수: 200이면 데이터도 맞다고 단정함 해결: 상태 코드와 JSON 스키마·값을 함께 검증합니다.
• 실수: 모든 실패를 서버 장애로 봄 해결: 4xx와 5xx를 먼저 구분합니다.
• 실수: PowerShell 예외 메시지만 읽음 해결: 응답 상태와 오류 본문을 함께 기록합니다.

✎7. 직접 실습

✎직접 실습

실습 목표

같은 서버에서 200·404·연결 실패를 재현하고 상태·헤더·본문의 차이를 기록합니다.

시작 전 상태

로컬 API와 /health를 먼저 PowerShell로 확인합니다. 실제 JWT·API Key는 사용하지 않고 테스트 결과 파일에도 비밀 값을 넣지 않습니다.

1단계: 따라 하기

예제 두 요청을 실행해 200과 404를 만듭니다. 각 결과의 status, Content-Type, body를 세 열 표로 작성합니다.

2단계: 값을 바꾸고 비교하기

/not-found를 /health로 바꾸면 같은 GET이 200이 되는지 확인합니다. 다시 서버를 안전하게 중지해 연결 실패에는 상태 코드와 JSON 본문이 없다는 차이를 기록한 뒤 서버를 재시작합니다.

3단계: 직접 적용

201, 204, 400, 401, 403, 422가 적합한 게임 기록 API 상황을 한 문장씩 작성합니다. 상태 코드만 정하지 말고 클라이언트가 어떤 화면 행동을 해야 하는지도 적습니다.

4단계: 스스로 확인

• 404와 연결 실패를 구분했나요?
• 200이어도 JSON 필드와 값까지 확인했나요?
• 오류 응답에서 상태와 detail을 함께 기록했나요?

막혔을 때

• 연결 거부: URL을 바꾸기 전에 서버 프로세스와 포트를 확인합니다.
• 404: 서버가 살아 있으므로 method와 path 철자를 확인합니다.
• HTML이 반환됨: 요청한 서버·경로가 API인지와 Content-Type을 확인합니다.
• PowerShell catch 속성이 없음: 현재 버전의 예외 객체 전체를 출력해 실제 Response·ErrorDetails 필드를 찾습니다.

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

?8. 이해 점검 질문 3개

?이해 점검

1. 요청과 응답에 공통으로 들어갈 수 있는 요소는 무엇인가요?
2. 4xx와 5xx의 책임 범위는 어떻게 다른가요?
3. /health가 200을 반환하지만 본문이 {"status":"down"}이라면 왜 성공으로 판정하면 안 되나요?

■9. 핵심 요약

■핵심 요약

HTTP 테스트의 최소 단위는 요청의 메서드·URL·헤더·본문과 응답의 상태·헤더·본문입니다. 성공과 실패 모두 의도대로 재현돼야 계약이 검증됩니다.

§다음 강의 연결

HTTP 메시지를 읽는 기준을 만들었으므로 3강. Postman 설치와 첫 GET 요청에서 같은 성공·실패 요청을 저장 가능한 GUI 요청으로 재현합니다.