Postman 사용법 | API 테스트 쉽게 하는 방법 초보자 가이드

이럴 때 가장 많이 사용하는 도구가 바로 Postman입니다. postman은 API를 직접 테스트할 수 있는 도구입니다.

브라우저에서 URL을 입력하듯이 API 주소를 넣고, GET 요청이나 POST 요청을 보내서 서버 응답을 확인할 수 있습니다. 특히 API를 처음 배우는 사람에게 Postman 사용법은 매우 유용합니다. Python requests 코드를 작성하기 전에 Postman으로 먼저 API 호출이 정상적으로 되는지 확인하면 오류를 훨씬 빠르게 찾을 수 있습니다.

이번 글에서는 Postman 사용법, API 테스트 방법, GET 요청과 POST 요청, Header와 Body 설정, JSON 응답 확인, 자주 발생하는 오류 해결법까지 초보자 기준으로 쉽게 정리해보겠습니다.

Postman이란?

Postman은 API를 테스트하고 관리할 수 있는 대표적인 API 테스트 도구입니다. 쉽게 말하면, 코드를 작성하지 않고 API 요청을 보내고 응답을 확인할 수 있는 프로그램입니다.

예를 들어 API 문서에 이런 주소가 있다고 해보겠습니다.

https://api.example.com/users

이 주소를 Postman에 입력하고 GET 요청을 보내면 서버에서 응답을 받을 수 있습니다.

응답은 보통 JSON 형태로 표시됩니다.

{
  "id": 1,
  "name": "Wing",
  "role": "developer"
}

즉, Postman은 API가 정상적으로 작동하는지 빠르게 확인할 수 있는 테스트 도구입니다.

Postman은 왜 필요할까?

API 테스트를 할 때는 확인해야 할 요소가 많습니다.

이 모든 것을 코드로만 확인하려면 초보자에게는 어렵게 느껴질 수 있습니다. Postman을 사용하면 화면에서 하나씩 설정하고 바로 응답을 확인할 수 있습니다.

웹사이트를 운영하거나 API 연동 기능을 만들 때도 Postman 사용법을 익혀두면 매우 편합니다.

예를 들어 win-j.com 같은 사이트에서 외부 API를 연결한다면, 실제 코드에 넣기 전에 Postman으로 먼저 테스트해볼 수 있습니다.

Postman 사용 방법 Step-by-Step

처음 Postman을 사용할 때는 아래 순서대로 진행하면 됩니다.

1. Postman 설치 또는 웹 버전 접속

Postman 바로가기

Postman은 프로그램으로 설치해서 사용할 수도 있고, 웹 브라우저에서 사용할 수도 있습니다.

초보자라면 처음에는 설치형 프로그램을 추천합니다. API 테스트를 반복적으로 할 때 더 안정적이고 사용하기 편합니다.

설치 후 실행하면 Workspace를 만들 수 있습니다.

Workspace는 API 테스트 요청들을 모아두는 작업 공간이라고 보면 됩니다.

2. 새 요청 만들기

Postman을 실행한 뒤 New 또는 + 버튼을 눌러 새 요청을 만듭니다.

요청 화면에는 보통 다음 요소가 있습니다.

처음에는 복잡해 보이지만 자주 쓰는 것은 Method, URL, Headers, Body 정도입니다.

3. GET 요청 테스트하기

GET 요청은 데이터를 조회할 때 사용합니다.

예를 들어 사용자 목록을 조회한다고 가정하면 다음과 같은 주소를 입력합니다.

https://api.example.com/users

Postman에서 Method를 GET으로 선택하고 URL을 입력한 뒤 Send 버튼을 누르면 됩니다.

정상 응답 예시는 다음과 같습니다.

[
  {
    "id": 1,
    "name": "Wing"
  },
  {
    "id": 2,
    "name": "Win-J"
  }
]

GET 요청은 검색, 조회, 목록 가져오기 같은 작업에서 많이 사용됩니다.

4. Query Parameter 입력하기

검색 API나 목록 API는 조건을 함께 보내야 할 때가 많습니다.

예를 들어 검색어와 페이지 번호를 보낸다면 URL은 이렇게 생길 수 있습니다.

https://api.example.com/search?keyword=python&page=1

Postman에서는 Params 탭에 아래처럼 입력할 수 있습니다.

Postman이 자동으로 URL 뒤에 파라미터를 붙여줍니다.

5. POST 요청 테스트하기

POST 요청은 데이터를 서버로 보낼 때 사용합니다.

예를 들어 게시글을 작성하는 API가 있다고 가정해보겠습니다.

https://api.example.com/posts

Postman에서 Method를 POST로 선택하고, Body 탭으로 이동합니다.

그다음 raw를 선택하고 형식을 JSON으로 바꾼 뒤 아래처럼 입력합니다.

{
  "title": "Postman 사용법",
  "content": "API 테스트 예제입니다."
}

그리고 Send 버튼을 누르면 서버로 JSON 데이터가 전송됩니다.

정상 응답 예시는 다음과 같습니다.

{
  "id": 10,
  "title": "Postman 사용법",
  "created": true
}

Header와 Authorization 이해하기

API를 테스트하다 보면 인증이 필요한 경우가 많습니다.

대표적으로 다음과 같은 정보가 Header에 들어갑니다.

예를 들어 API Key를 Header에 넣어야 한다면 다음처럼 설정합니다.

Bearer Token 방식이라면 다음처럼 입력할 수 있습니다.

또는 Postman의 Authorization 탭에서 Type을 Bearer Token으로 선택하고 토큰을 입력해도 됩니다.

Postman 결과 화면 보는 방법

Postman에서 Send 버튼을 누르면 아래쪽 Response 영역에 결과가 표시됩니다.

확인해야 할 핵심은 다음과 같습니다.

예를 들어 200 OK가 표시되면 요청이 성공한 것입니다.

반대로 404 Not Found, 401 Unauthorized, 500 Internal Server Error가 나오면 오류 원인을 확인해야 합니다.

Postman 테스트 후 Python 코드로 옮기기

Postman으로 API 테스트가 성공했다면 이제 Python requests 코드로 옮길 수 있습니다.

GET 요청 예시:

import requests

url = "https://api.example.com/users"

response = requests.get(url)

print(response.status_code)
print(response.json())

POST 요청 예시:

import requests

url = "https://api.example.com/posts"

headers = {
    "Content-Type": "application/json"
}

data = {
    "title": "Postman 사용법",
    "content": "API 테스트 예제입니다."
}

response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())

Postman에서 성공한 요청을 Python 코드로 바꿔보면 API 구조를 더 쉽게 이해할 수 있습니다.

무료 vs 유료 비교

Postman은 기본적인 API 테스트 기능을 무료로 사용할 수 있습니다.
다만 팀 협업, 고급 관리 기능, 모니터링 기능 등은 유료 플랜에서 더 강력하게 제공됩니다.

초보자나 개인 블로그 운영자가 API 테스트를 하는 정도라면 무료 기능만으로도 충분합니다.

자주 발생하는 오류 및 해결법

1. 400 Bad Request

요청 형식이 잘못되었을 때 발생합니다.

확인할 것:

2. 401 Unauthorized

인증 실패 오류입니다.

확인할 것:

3. 403 Forbidden

권한이 없을 때 발생합니다.

확인할 것:

4. 404 Not Found

API 주소가 잘못되었을 때 발생합니다.

확인할 것:

5. 429 Too Many Requests

호출 제한을 초과했을 때 발생합니다.

확인할 것:

6. 500 Internal Server Error

서버 내부 오류입니다.

이 경우 클라이언트 설정 문제가 아닐 수도 있습니다.

확인할 것:

실전 활용 팁

1. API 문서를 옆에 두고 테스트하기

Postman 사용법에서 가장 중요한 것은 API 문서와 함께 보는 것입니다.

문서에는 보통 다음 정보가 있습니다.

문서와 Postman 화면을 나란히 보면서 하나씩 입력하면 실수가 줄어듭니다.

2. Collection으로 요청 정리하기

자주 테스트하는 API는 Collection으로 묶어두면 좋습니다.

예를 들어:

이렇게 나누어두면 나중에 다시 테스트할 때 편합니다.

3. 민감한 API Key는 조심하기

API Key나 Token은 외부에 노출되면 안 됩니다.

특히 화면 캡처, 블로그 글 작성, GitHub 업로드 시 주의해야 합니다.

Authorization: Bearer YOUR_TOKEN

글이나 예제에서는 실제 키 대신 반드시 YOUR_TOKEN, YOUR_API_KEY처럼 표시하는 것이 좋습니다.

4. 성공한 요청을 코드로 변환하기

Postman은 요청을 다양한 언어 코드로 변환하는 기능도 제공합니다.

Python, JavaScript, cURL 등으로 변환할 수 있어 API 연동을 시작할 때 도움이 됩니다.

초보자는 Postman에서 먼저 성공시킨 뒤 Python requests로 옮기는 방식을 추천합니다.

이런 사람에게 추천합니다

Postman은 이런 사람에게 추천합니다.

마무리

Postman은 API를 처음 배우는 사람에게 가장 유용한 도구 중 하나입니다.

핵심만 정리하면 다음과 같습니다.

API를 공부할 때 처음부터 코드로만 접근하면 어렵게 느껴질 수 있습니다. 하지만 Postman으로 먼저 API 호출 흐름을 눈으로 확인하면 Request와 Response 구조를 훨씬 쉽게 이해할 수 있습니다. 이후 Python requests로 코드를 작성하면 API 사용법이 자연스럽게 연결됩니다. 웹 개발, 자동화, AI API 연동, 쇼핑 API 활용을 생각하고 있다면 Postman 사용법은 꼭 익혀두는 것을 추천합니다.