3강. Postman 설치와 첫 GET 요청

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

게임 기록·랭킹 API를 테스트하면서 Windows에 Postman을 설치하고 로그인 없이 로컬 GET 요청을 보냅니다. 수동으로 한 번 성공하는 데서 끝내지 않고 같은 결과를 다시 확인할 수 있는 요청으로 남깁니다.

✓2. 학습 목표

✓이 강의를 마치면

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

◇3. 핵심 개념

Postman Desktop 앱은 로그인하지 않아도 경량 API 클라이언트로 요청을 만들고 로컬 기록을 유지할 수 있습니다. 계정과 클라우드 동기화는 협업 선택 사항이지 이 과정의 필수 조건이 아닙니다. 설치 화면과 메뉴 이름은 바뀔 수 있으므로 설치 단계는 Postman 공식 문서의 최신 화면을 우선합니다.

Postman은 API를 대신 만들어 주는 서버가 아니라 HTTP 클라이언트입니다. method·URL·headers·body를 입력해 요청을 보내고, 받은 status·headers·body를 보기 쉽게 나눠 보여 줍니다. PowerShell과 같은 요청을 보낸다면 서버는 어느 도구에서 왔는지와 관계없이 같은 계약으로 응답해야 합니다.

첫 GET 요청의 입력과 기대값

입력	값	이유
method	GET	상태를 읽기만 함
URL	http://127.0.0.1:8000/health	로컬 서버의 health 경로
body	없음	조회에 전달할 생성 데이터가 없음
기대 status	200 OK	서버와 경로가 정상
기대 body	{"status":"ok"}	상태 계약이 정상

버튼을 누르기 전에 기대값을 먼저 적으면 단순히 "초록색이 보였다"가 아니라 계약이 맞는지 판정할 수 있습니다.

✎4. 단계별 실습

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

실행 전 상태: FastAPI 서버 터미널이 실행 중이고 PowerShell GET /health가 성공해야 합니다. Postman 설치 파일은 공식 출처에서 받고 설치 경로와 앱 버전을 실습 기록에 남깁니다.

1. 공식 설치 문서에서 Windows용 Desktop 앱을 내려받아 설치합니다.
2. 로그인 화면에서는 계정 없이 사용할 수 있는 경량 클라이언트 진입을 선택합니다.
3. 새 HTTP 요청을 열고 메서드 GET, URL {{baseUrl}}/health 대신 우선 실제 주소를 입력해 Send를 누릅니다.
4. Status, Time, Body 패널을 확인합니다.

화면에서 확인할 순서

1. method가 GET인지 확인합니다. 다른 method가 남아 있으면 같은 URL에서도 405가 날 수 있습니다.
2. URL의 프로토콜 http, 호스트 127.0.0.1, 포트 8000, path /health를 나누어 읽습니다.
3. Send를 누른 뒤 status가 200인지 확인합니다.
4. Headers에서 응답 Content-Type이 JSON인지 확인합니다.
5. Body의 status 필드가 ok인지 확인합니다.
6. 요청 이름을 Health - 성공으로 저장해 다음 실행에서도 같은 입력을 사용합니다.

PowerShell

$baseUrl = "http://127.0.0.1:8000"
Invoke-RestMethod -Method Get -Uri "$baseUrl/health"

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

구체적인 성공과 실패 결과 비교

상황	Postman 결과	확인할 원인
정상 서버와 /health	200 + JSON	계약 필드와 값
/heath 오타	404 + 오류 JSON	path 철자
POST로 잘못 보냄	405 가능	method 등록 여부
서버 중지	연결 오류, HTTP status 없음	프로세스·포트

응답 시간은 컴퓨터 상태에 따라 달라지므로 한 번의 숫자를 성능 결론으로 사용하지 않습니다. 이 강의에서는 요청이 도착하고 계약이 맞는지만 확인합니다.

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

Postman도 PowerShell과 마찬가지로 표준 HTTP 요청을 보냅니다. GUI는 메서드·URL·헤더·본문을 탭으로 나눠 보여 주고, 서버 응답을 상태·시간·크기·본문으로 시각화할 뿐 프로토콜 자체를 바꾸지 않습니다.

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

!자주 하는 실수

• 실수: 계정이 반드시 필요하다고 생각함 해결: 개인 로컬 실습은 로그아웃 상태의 경량 클라이언트로 진행할 수 있습니다.
• 실수: 웹 앱에서 로컬 서버 연결이 안 됨 해결: Desktop 앱 또는 공식 Desktop Agent 요구사항을 확인합니다.
• 실수: Send 전에 서버 주소를 확인하지 않음 해결: PowerShell의 /health 요청부터 성공시킵니다.

✎7. 직접 실습

✎직접 실습

실습 목표

첫 GET 요청을 저장하고 path·method·서버 상태를 바꿔 서로 다른 실패 결과를 구분합니다.

시작 전 상태

PowerShell에서 /health가 성공한 뒤 Postman을 엽니다. 실제 인증 정보는 입력하지 않습니다.

1단계: 따라 하기

GET과 실제 URL을 입력해 Send를 누릅니다. status 200, JSON Content-Type, status: ok를 확인하고 Health - 성공으로 저장합니다.

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

path를 /heath로 바꿔 404를 확인한 뒤 원래대로 복구합니다. JSON을 Pretty와 Raw로 번갈아 보며 표시 방식만 달라지고 실제 본문 값은 같다는 점을 확인합니다.

3단계: 직접 적용

서버를 중지해 연결 실패를 만든 뒤 404와 차이를 기록합니다. 서버를 다시 실행하고 저장된 요청을 재전송해 200으로 복구되는지 확인합니다.

4단계: 스스로 확인

• 저장된 요청에 method와 URL이 정확히 남았나요?
• 200과 JSON 필드까지 함께 판정했나요?
• 서버 중지 실험 후 프로세스를 다시 실행했나요?

막혔을 때

• Postman만 연결 실패: PowerShell 요청과 비교하고 Desktop 앱/Agent 사용 상태를 확인합니다.
• 404: 연결은 성공했으므로 path 오타와 서버 라우트를 확인합니다.
• 405: URL보다 method가 맞는지 확인합니다.
• 200인데 기대 JSON이 아님: Content-Type과 body의 필드·값, 다른 포트의 서버에 연결했는지 확인합니다.

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

?8. 이해 점검 질문 3개

?이해 점검

1. Postman 계정 없이 가능한 작업은 무엇인가요?
2. Postman과 PowerShell 요청의 공통점은 무엇인가요?
3. Postman에서는 연결 오류가 나지만 PowerShell /health는 200일 때 어느 쪽의 환경을 먼저 조사해야 하나요?

■9. 핵심 요약

■핵심 요약

Postman은 계정 없이도 로컬 API 테스트에 사용할 수 있습니다. 첫 GET 요청을 저장해 이후 모든 요청의 기준점으로 삼습니다.

§다음 강의 연결

고정 URL의 첫 요청을 저장했습니다. 4강. URL·Path·Query 매개변수에서 상세 ID와 필터 값을 바꾸며 요청 대상을 구분합니다.