Postman 실전 가이드 - REST API 테스트부터 자동화까지 완벽 사용법

Postman 실전 가이드 - REST API 테스트부터 자동화까지 완벽 사용법

📌 소개: 현대 API 개발의 필수 도구, Postman

 

Postman은 단순한 API 테스트 도구를 넘어 API 설계, 문서화, 자동화, 협업까지 지원하는 종합 API 개발 플랫폼으로 성장했습니다.

이 글에서는 기본 사용법부터 고급 자동화 기능까지 단계별로 살펴보겠습니다.

 

💡 이 글이 필요한 사람:

Postman을 처음 사용하는 개발자
API 테스트 과정을 효율화하고 싶은 개발자
API 문서화 및 팀 협업 방법을 찾는 개발자
CI/CD 파이프라인에 API 테스트를 통합하고 싶은 개발자

🚀 Postman의 기본 개념 이해하기

Postman이란?

Postman은 API(Application Programming Interface) 개발 라이프사이클의 모든 단계를 지원하는 협업 플랫폼입니다. 2012년에 처음 출시된 이후 현재는 2,500만 명 이상의 개발자가 사용하는 업계 표준 도구로 자리 잡았습니다.

주요 특징은 다음과 같습니다:

• API 테스트: HTTP 요청을 쉽게 생성하고 응답을 검증
• 자동화: 반복적인 테스트를 자동화하여 시간 절약
• 문서화: API 문서를 자동으로 생성하고 공유
• 협업: 팀 워크스페이스에서 API 정의와 테스트 케이스 공유
• 모니터링: API 성능 및 가용성 모니터링
• 모의 서버(Mock Server): 백엔드 개발 없이 API 프로토타입 제작

Postman 설치 및 초기 설정

1. Postman 공식 웹사이트에서 운영체제에 맞는 버전을 다운로드합니다.
2. 설치 파일을 실행하고 안내에 따라 설치를 완료합니다.
3. 회원가입 또는 로그인을 합니다. (무료 계정으로도 기본 기능을 충분히 사용할 수 있습니다.)
4. 기본 워크스페이스를 선택하고 시작합니다.

📝 기본 API 요청 테스트하기

1. 첫 번째 HTTP 요청 생성하기

1. 왼쪽 상단의 "New" 버튼 클릭
2. "HTTP Request" 선택
3. HTTP 메서드(GET, POST, PUT, DELETE 등) 선택
4. URL 입력 (예: https://jsonplaceholder.typicode.com/posts)
5. "Send" 버튼 클릭

2. 다양한 HTTP 메서드 사용하기

GET 요청 예제

GET https://jsonplaceholder.typicode.com/posts/1

POST 요청 예제

POST https://jsonplaceholder.typicode.com/posts
Body (raw - JSON):
{
    "title": "foo",
    "body": "bar",
    "userId": 1
}

PUT 요청 예제

PUT https://jsonplaceholder.typicode.com/posts/1
Body (raw - JSON):
{
    "id": 1,
    "title": "updated title",
    "body": "updated body",
    "userId": 1
}

DELETE 요청 예제

DELETE https://jsonplaceholder.typicode.com/posts/1

3. 요청 헤더 및 파라미터 설정

API 요청에는 종종 헤더와 파라미터가 필요합니다. Postman에서 이를 쉽게 설정할 수 있습니다.

헤더 추가하기

1. 요청 영역에서 "Headers" 탭 선택
2. "Key-Value" 형식으로 헤더 입력
   - Content-Type: application/json
   - Authorization: Bearer your_token_here

쿼리 파라미터 추가하기

1. 요청 영역에서 "Params" 탭 선택
2. "Query Params" 섹션에 키-값 쌍 입력
   - page: 1
   - limit: 10

4. 요청 바디(Body) 작성하기

Postman은 다양한 형식의 요청 본문을 지원합니다:

Raw (JSON)

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Form-data

1. "Body" 탭에서 "form-data" 선택
2. 키-값 쌍 입력 (파일 업로드도 가능)
   - name: John Doe
   - profile_image: [파일 선택]

x-www-form-urlencoded

1. "Body" 탭에서 "x-www-form-urlencoded" 선택
2. 키-값 쌍 입력
   - username: johndoe
   - password: mysecretpassword

5. 응답 분석하기

API 응답을 보고 분석하는 것은 Postman의 핵심 기능입니다.

응답 상태 코드

• 2xx: 성공 (200 OK, 201 Created 등)
• 3xx: 리다이렉션
• 4xx: 클라이언트 오류 (400 Bad Request, 404 Not Found 등)
• 5xx: 서버 오류

응답 시간

• 응답 시간이 표시되어 성능 문제를 확인할 수 있습니다.

응답 본문 보기

• Pretty: 형식화된 JSON/XML 보기
• Raw: 원시 텍스트
• Preview: HTML 렌더링 보기
• Visualize: 차트로 시각화 (Beta 기능)

🔄 컬렉션으로 작업 구성하기

1. 컬렉션 생성 및 구성

컬렉션은 관련된 API 요청을 그룹화하는 폴더입니다. 프로젝트나 기능별로 API를 구성할 수 있습니다.

1. 왼쪽 사이드바에서 "Collections" 탭 선택
2. "+" 버튼을 클릭하여 새 컬렉션 생성
3. 컬렉션 이름 입력 (예: "사용자 관리 API")
4. 폴더를 추가하여 하위 카테고리 생성 가능
   - 사용자 목록
   - 사용자 상세
   - 사용자 생성/수정/삭제

2. 요청 저장하기

테스트한 요청을 컬렉션에 저장하여 재사용할 수 있습니다.

1. 요청 작성 후 "Save" 버튼 클릭
2. 요청 이름 입력 (예: "사용자 목록 조회")
3. 저장할 컬렉션/폴더 선택
4. "Save" 버튼 클릭

3. 환경 설정하기

환경은 다양한 설정(개발, 테스트, 프로덕션 등)에서 사용할 변수 집합입니다.

1. 오른쪽 상단의 "환경" 아이콘 클릭
2. "+" 버튼을 클릭하여 새 환경 생성
3. 환경 이름 입력 (예: "개발 환경")
4. 변수 추가:
   - base_url: http://localhost:8080/api
   - api_key: dev_api_key_here
5. "Save" 버튼 클릭

4. 변수 사용하기

환경 변수를 사용하면 요청을 쉽게 재사용할 수 있습니다.

1. 요청 URL에 변수 사용:
   {{base_url}}/users

2. 헤더에 변수 사용:
   Authorization: Bearer {{access_token}}

3. 요청 본문에 변수 사용:
   {
     "api_key": "{{api_key}}",
     "user_id": "{{user_id}}"
   }

🤖 테스트 자동화하기

1. 테스트 스크립트 작성

Postman에서는 JavaScript를 사용하여 응답을 검증하는 테스트를 작성할 수 있습니다.

// 기본 상태 코드 테스트
pm.test("Status code is 200", function() {
    pm.response.to.have.status(200);
});

// 응답 시간 테스트
pm.test("Response time is less than 500ms", function() {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// JSON 응답 데이터 테스트
pm.test("Response has correct user data", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.name).to.eql("John Doe");
    pm.expect(jsonData.email).to.eql("john@example.com");
    pm.expect(jsonData.id).to.exist;
});

// 헤더 테스트
pm.test("Content-Type header is present", function() {
    pm.response.to.have.header("Content-Type");
    pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});

2. 사전 요청 스크립트(Pre-request Script)

요청 전에 실행되는 스크립트로, 인증 토큰 생성이나 데이터 준비에 유용합니다.

// 현재 타임스탬프 생성
var timestamp = new Date().getTime();
pm.environment.set("timestamp", timestamp);

// 랜덤 ID 생성
var randomId = Math.floor(Math.random() * 1000);
pm.environment.set("random_id", randomId);

// JWT 토큰 생성 (예시)
const jwt = require('jsonwebtoken');
const token = jwt.sign(
    { user_id: pm.environment.get("user_id") },
    'secret_key',
    { expiresIn: '1h' }
);
pm.environment.set("access_token", token);

3. 컬렉션 러너로 테스트 실행

여러 요청을 순차적으로 실행하여 전체 API 플로우를 테스트할 수 있습니다.

1. 컬렉션 이름 옆의 "..." 메뉴 클릭
2. "Run collection" 선택
3. 실행할 요청 선택
4. 환경 선택
5. 반복 횟수, 지연 시간 등 설정
6. "Run" 버튼 클릭
7. 테스트 결과 확인

4. Newman으로 CLI 테스트 자동화

Newman은 Postman 컬렉션을 커맨드 라인에서 실행할 수 있는 도구로, CI/CD 파이프라인 통합에 유용합니다.

# Newman 설치
npm install -g newman

# 컬렉션 실행
newman run my-collection.json -e my-environment.json

# HTML 리포트 생성
npm install -g newman-reporter-htmlextra
newman run my-collection.json -e my-environment.json -r htmlextra

📊 모니터링 및 문서화

1. API 모니터링 설정

정기적으로 API를 테스트하여 성능과 가용성을 모니터링할 수 있습니다.

1. 컬렉션 이름 옆의 "..." 메뉴 클릭
2. "Monitor Collection" 선택
3. 모니터 이름 입력
4. 실행 주기 설정 (예: 5분마다, 1시간마다, 1일마다)
5. 환경 선택
6. 알림 설정 (이메일, Slack 등)
7. "Create" 버튼 클릭

2. API 문서 자동 생성

Postman은 컬렉션을 기반으로, 테스트와 예제를 포함한 API 문서를 자동으로 생성합니다.

1. 컬렉션 이름 옆의 "..." 메뉴 클릭
2. "View Documentation" 선택
3. "Publish" 버튼 클릭하여 공개 URL 생성
4. 문서 사용자 지정:
   - 설명 추가
   - 예제 추가
   - 마크다운 포맷팅 사용

3. 팀 협업 기능

Postman의 팀 워크스페이스를 통해 API 개발에 협업할 수 있습니다.

1. 오른쪽 상단에서 워크스페이스 선택
2. "Create Workspace" 클릭
3. "Team" 유형 선택
4. 워크스페이스 이름 및 설명 입력
5. 팀원 초대 (이메일 주소 입력)
6. 컬렉션과 환경 공유

🔍 실전 활용 사례와 고급 기능

1. OAuth 2.0 인증 설정

많은 API가 OAuth 2.0 인증을 사용합니다. Postman에서 쉽게 설정할 수 있습니다.

1. 요청의 "Authorization" 탭 선택
2. Type 드롭다운에서 "OAuth 2.0" 선택
3. 필요한 파라미터 입력:
   - Token Name: My API Token
   - Grant Type: Authorization Code, Client Credentials 등
   - Access Token URL: https://api.example.com/oauth/token
   - Client ID와 Client Secret 입력
4. "Get New Access Token" 버튼 클릭
5. 발급받은 토큰을 요청에 사용

2. 모의 서버(Mock Server) 생성

백엔드 개발 완료 전에 API 프로토타입을 테스트할 수 있습니다.

1. 컬렉션 이름 옆의 "..." 메뉴 클릭
2. "Mock Collection" 선택
3. 모의 서버 이름 입력
4. 환경 선택 (선택 사항)
5. "Create Mock Server" 버튼 클릭
6. 생성된 모의 서버 URL 사용

3. 데이터 주도 테스트(Data-driven Testing)

CSV나 JSON 파일을 사용하여 다양한 데이터로 API를 테스트할 수 있습니다.

1. 컬렉션 러너에서 "Data" 탭 선택
2. CSV 또는 JSON 파일 선택
3. 각 데이터 행을 반복하여 테스트 실행
4. 스크립트에서 데이터 변수 접근:
   var data = pm.iterationData.get("username");

4. 그래프QL API 테스트

Postman은 GraphQL API 테스트도 지원합니다.

1. POST 요청 생성
2. URL 입력 (예: https://api.example.com/graphql)
3. Body 탭에서 GraphQL 선택
4. 쿼리 작성:
   query {
     user(id: "123") {
       id
       name
       email
       posts {
         title
       }
     }
   }
5. 변수 탭에서 쿼리 변수 정의 (필요한 경우)

🛠️ 실전 프로젝트: Spring Boot REST API 테스트

1. 사용자 관리 API 테스트 시나리오

아래는 Spring Boot로 개발된 사용자 관리 API를 테스트하는 샘플 컬렉션입니다.

1) 사용자 생성 (POST)

POST {{base_url}}/api/users
Content-Type: application/json

{
  "username": "johndoe",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "securePassword123"
}

// 테스트 스크립트
pm.test("Status code is 201", function() {
    pm.response.to.have.status(201);
});

pm.test("User created successfully", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.id).to.exist;
    pm.environment.set("user_id", jsonData.id);
});

2) 사용자 목록 조회 (GET)

GET {{base_url}}/api/users?page=0&size=10
Accept: application/json

// 테스트 스크립트
pm.test("Status code is 200", function() {
    pm.response.to.have.status(200);
});

pm.test("Response contains users array", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.content).to.be.an('array');
});

3) 사용자 상세 조회 (GET)

GET {{base_url}}/api/users/{{user_id}}
Accept: application/json

// 테스트 스크립트
pm.test("Status code is 200", function() {
    pm.response.to.have.status(200);
});

pm.test("User details are correct", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.id).to.eql(pm.environment.get("user_id"));
    pm.expect(jsonData.username).to.eql("johndoe");
    pm.expect(jsonData.email).to.eql("john@example.com");
});

4) 사용자 정보 수정 (PUT)

PUT {{base_url}}/api/users/{{user_id}}
Content-Type: application/json

{
  "email": "john.updated@example.com",
  "firstName": "Johnny",
  "lastName": "Doe"
}

// 테스트 스크립트
pm.test("Status code is 200", function() {
    pm.response.to.have.status(200);
});

pm.test("User updated successfully", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.email).to.eql("john.updated@example.com");
    pm.expect(jsonData.firstName).to.eql("Johnny");
});

5) 사용자 삭제 (DELETE)

DELETE {{base_url}}/api/users/{{user_id}}

// 테스트 스크립트
pm.test("Status code is 204", function() {
    pm.response.to.have.status(204);
});

// 삭제 확인 테스트
setTimeout(function() {
    pm.sendRequest({
        url: pm.environment.get("base_url") + "/api/users/" + pm.environment.get("user_id"),
        method: 'GET'
    }, function(err, res) {
        pm.test("User should not exist", function() {
            pm.expect(res.code).to.eql(404);
        });
    });
}, 500);

2. 통합 테스트 워크플로우

전체 워크플로우를 자동화하기 위한 컬렉션 실행 시나리오입니다.

1. 인증 토큰 획득 (로그인)
2. 사용자 생성
3. 생성된 사용자 ID 저장
4. 사용자 목록 조회
5. 사용자 상세 조회
6. 사용자 정보 수정
7. 수정된 정보 확인
8. 사용자 삭제
9. 삭제 확인

이 워크플로우를 컬렉션 러너나 Newman을 통해 CI/CD 파이프라인에 통합할 수 있습니다.

📈 Postman 활용 성공 사례

1. API 개발 시간 단축

팀 A는 Postman 도입 후 API 개발 시간을 30% 단축했습니다:
- 모의 서버로 프론트엔드와 백엔드 개발 병렬화
- 자동화된 테스트로 회귀 오류 감소
- 문서 자동 생성으로 커뮤니케이션 향상

2. QA 프로세스 개선

팀 B는 Postman으로 QA 프로세스를 개선했습니다:
- 테스트 케이스의 재사용성 증가
- 데이터 주도 테스트로 다양한 시나리오 검증
- CI/CD 파이프라인에 API 테스트 통합

🏁 결론: API 개발의 효율성을 높이는 Postman

Postman은 단순한 API 테스트 도구를 넘어 API 개발 라이프사이클 전반을 지원하는 강력한 플랫폼입니다. 이 글에서 다룬 기능들을 활용하면 API 개발, 테스트, 문서화, 협업 과정을 크게 개선할 수 있습니다.

기본적인 HTTP 요청부터 복잡한 자동화 테스트, CI/CD 파이프라인 통합까지, Postman은 모든 수준의 개발자에게 유용한 도구입니다. 특히 팀 협업 기능과 자동화 기능은 대규모 프로젝트에서 큰 가치를 발휘합니다.

다음 단계로, Postman의 고급 기능인 워크스페이스와 API 설계 도구를 활용하여 API-First 개발 방법론을 적용해 보세요. 이를 통해 더욱 효율적이고 일관된 API 개발이 가능해집니다.

🔍 자주 묻는 질문 (FAQ)

Q: Postman은 무료인가요?

A: 기본적인 기능은 무료로 제공됩니다. 개인 사용자는 대부분의 기능을 무료로 사용할 수 있으며, 팀 협업, 고급 모니터링 등의 기능은 유료 플랜에서 제공됩니다.

Q: Postman 컬렉션을 팀원과 공유하는 방법은 무엇인가요?

A: 팀 워크스페이스를 생성하고 팀원을 초대하거나, 컬렉션을 JSON 파일로 내보내어 공유할 수 있습니다. 또한 "Share Collection" 기능을 통해 링크로 공유할 수도 있습니다.

Q: API 응답이 너무 큰 경우 어떻게 처리하나요?

A: Postman은 대용량 응답 처리를 위한 옵션을 제공합니다. 설정에서 "Request Size / Response Size" 제한을 조정하거나, 특정 필드만 추출하는 테스트 스크립트를 작성할 수 있습니다.

Q: 환경 변수와 전역 변수의 차이점은 무엇인가요?

A: 환경 변수는 특정 환경(개발, 테스트, 프로덕션 등)에 종속된 변수이고, 전역 변수는 모든 환경에서 공통으로 사용되는 변수입니다. 상황에 맞게 적절한 변수 유형을 선택하세요.