1강. API와 HTTP의 역할, API 클라이언트가 필요한 이유

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

게임 기록·랭킹 API를 테스트하면서 API와 HTTP의 역할을 구분하고 브라우저 대신 API 클라이언트로 게임 랭킹 서버를 확인하는 문제를 해결합니다. 수동으로 한 번 성공하는 데서 끝내지 않고 같은 결과를 다시 확인할 수 있는 요청으로 남깁니다.

✓2. 학습 목표

✓이 강의를 마치면

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

◇3. 핵심 개념

API는 두 프로그램이 합의한 입력과 출력의 규칙이고, HTTP는 그 메시지를 전달하는 대표적인 통신 규약입니다. 브라우저 주소창은 주로 GET만 보내지만 API 클라이언트는 메서드, 헤더, 본문, 인증 값을 직접 조합하고 응답을 반복 검증합니다. 이 과정에서는 http://127.0.0.1:8000에서 실행 중인 게임 기록·랭킹 API를 대상으로 삼습니다.

✎4. 단계별 실습

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

1. FastAPI 프로젝트 터미널에서 서버를 실행합니다.
2. 새 PowerShell 창에서 상태 확인 요청을 보냅니다.
3. URI, 메서드, 응답 본문을 한 줄씩 기록합니다.

PowerShell

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

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

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

Invoke-RestMethod가 HTTP GET 요청을 보내면 Uvicorn이 경로를 FastAPI 라우터에 전달합니다. 서버는 상태 코드와 JSON을 돌려주고 PowerShell은 JSON을 객체로 역직렬화해 속성으로 읽을 수 있게 합니다.

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

!자주 하는 실수

• 실수: 웹 페이지와 API를 같다고 생각함 해결: API 응답은 화면이 아니라 상태 코드·헤더·본문으로 판단합니다.
• 실수: 서버를 실행하지 않고 요청함 해결: 서버 터미널에서 Uvicorn 주소와 오류를 먼저 확인합니다.
• 실수: localhost의 포트를 생략함 해결: 예제 서버 포트 8000까지 정확히 적습니다.

✎7. 직접 실습

✎직접 실습

1. /health 응답에서 속성 이름과 값을 적습니다.
2. 존재하지 않는 /health-check를 요청해 성공 응답과 비교합니다.
3. 같은 요청을 세 번 실행해 반복 가능한지 확인합니다.

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

?8. 이해 점검 질문 3개

?이해 점검

1. API와 HTTP는 각각 어떤 역할을 하나요?
2. 주소창보다 API 클라이언트가 테스트에 적합한 이유는 무엇인가요?
3. 연결 실패와 404 응답은 어떻게 다른가요?

■9. 핵심 요약

■핵심 요약

API는 프로그램 사이의 계약이고 HTTP는 요청과 응답을 운반합니다. API 클라이언트는 계약의 모든 요소를 직접 구성하고 재현하는 실험 도구입니다.