Postman이란: API 테스트와 요청 다루기

Postman이란 무엇이며 주요 기능

Postman은 API 개발 및 테스트를 위한 플랫폼으로, 데스크톱 애플리케이션(Windows, macOS, Linux)과 웹 버전으로 제공됩니다. 2012년 Chrome 확장 프로그램으로 처음 만들어진 Postman은 모니터링, mock 서버 및 클라이언트 코드 생성 지원을 갖춘 완전한 생태계로 성장했습니다.

요청 및 응답 형식

Postman은 모든 HTTP 메서드(GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)를 지원합니다. 요청 본문은 JSON, XML, form-data, x-www-form-urlencoded, binary 형식일 수 있습니다. 응답은 구문 강조, Pretty-print 및 원시 헤더 보기 기능과 함께 표시됩니다.

인증 지원

내장 인증 유형에는 Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0, API Key 및 AWS Signature가 포함됩니다. Postman은 선택한 유형에 따라 Authorization 헤더를 자동으로 추가하므로 토큰을 수동으로 복사하지 않고도 보호된 엔드포인트를 빠르게 테스트할 수 있습니다.

Postman 인터페이스와 탐색

Postman 인터페이스는 사이드 패널(Collections, APIs, Environments), 작업 영역(Request Builder/Response Viewer), 하단 패널(Console, Runner)로 구성됩니다. Params 탭에서는 URL의 쿼리 매개변수를 표 형식으로 편집할 수 있고, Headers 탭에서는 HTTP 헤더를 관리할 수 있습니다.

Postman Console

Console(View → Show Postman Console)은 중간 리디렉션과 헤더를 포함한 모든 네트워크 요청과 응답을 시간순으로 기록합니다. 표준 Response Viewer가 최종 결과만 표시할 때 복잡한 OAuth 흐름과 리디렉션 체인을 디버깅하는 데 없어서는 안 될 도구입니다.

Workspaces와 팀 작업

Postman은 Fork와 Merge를 통한 컬렉션 버전 관리가 포함된 팀 작업 공간을 지원합니다. 팀 구성원은 요청에 댓글을 달고, 변경을 제안하고, 실시간으로 컬렉션을 동기화할 수 있습니다. Public Workspace를 사용하면 외부 개발자를 위한 API 문서를 게시할 수 있습니다.

HTTP 요청 만들기 및 보내기

Postman에서 기본 요청은 HTTP 메서드를 선택하고 주소 표시줄에 URL을 입력하여 생성됩니다. 전송 후 응답은 상태 코드, 실행 시간 및 크기와 함께 하단 패널에 표시됩니다. 요청 매개변수는 입력 시 자동으로 인코딩됩니다.

동적 변수와 스니펫

URL과 요청 본문에서 {{$variable}} 형식의 동적 변수를 사용할 수 있습니다. 내장 변수 {{$guid}}, {{$timestamp}}, {{$randomInt}}는 각 요청에 대해 고유한 값을 생성합니다. 코드 스니펫은 Code 버튼()을 통해 사용할 수 있으며, cURL, Python, JavaScript, Kotlin, Swift 등 다양한 언어로 동일한 요청을 생성합니다.

// Pre-request의 스크립트 예: HMAC 서명 생성
const timestamp = Date.now().toString();
const secret = pm.environment.get("api_secret");
const hash = CryptoJS.HmacSHA256(timestamp, secret);
pm.request.headers.add({
    key: "X-Signature",
    value: hash.toString()
});

컬렉션과 환경 변수

컬렉션은 프로젝트 또는 기능 모듈별로 묶인 관련 요청 그룹입니다. 각 컬렉션에는 중첩 폴더, 공유 헤더 및 컬렉션의 각 요청 전에 실행되는 Pre-request 스크립트가 포함될 수 있습니다. 요청 순서는 드래그하여 설정합니다.

환경 변수와 전역 변수

Postman은 다섯 가지 변수 수준을 지원합니다: global, collection, environment, data, local. 충돌 해결 우선순위는 로컬에서 글로벌 순서입니다. 환경 파일에는 development, staging, production 등 다양한 환경에 대한 키-값 쌍이 포함됩니다. 환경을 전환하면 모든 URL과 토큰이 자동으로 변경됩니다.

스크립트를 통한 API 테스트 자동화

Postman은 응답을 받은 후 실행되는 Tests 탭에서 JavaScript로 테스트를 작성할 수 있게 해줍니다. 테스트는 상태 코드, 응답 본문, 헤더 및 실행 시간을 검증합니다. 결과는 색상으로 구분된 통과 표시기와 함께 Test Results 패널에 표시됩니다.

pm 라이브러리와 요청 체이닝

pm 객체는 응답을 처리하는 메서드를 제공합니다: pm.response, pm.expect, pm.variables. 요청 체이닝은 한 요청의 응답에서 데이터를 변수에 저장하고 다음 요청에서 사용하는 방식으로 구현됩니다. 이것은 통합 테스트 구축과 일련의 API 호출을 통한 비즈니스 로직 검증의 기초입니다.

// 테스트: 응답 구조 확인 및 토큰 저장
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set("auth_token", json.data.token);

Collection Runner와 Newman

Collection Runner는 컬렉션의 모든 요청을 순차적으로 실행하며 각 단계에서 테스트를 실행합니다. Newman은 CI/CD 파이프라인(Jenkins, GitHub Actions, GitLab CI)용 Postman의 콘솔 버전입니다. Newman은 모니터링 시스템과의 통합을 위해 JSON, JUnit 및 HTML 형식으로 보고서를 내보냅니다.

GraphQL과 WebSocket 다루기

Postman의 GraphQL 요청은 JSON 형식의 본문과 함께 단일 엔드포인트에 POST로 전송됩니다. GraphQL(Beta) 탭은 구문 강조, 필드 자동 완성 및 스키마를 갖춘 시각적 편집기를 제공합니다. 요청 변수는 별도의 Variables 패널에서 전달됩니다.

WebSocket 및 Socket.IO 테스트

Postman은 메시지 패널이 있는 별도 인터페이스를 통해 WebSocket 연결을 지원합니다. 텍스트 및 바이너리 메시지를 보내고, 연결 기록을 보고, 연결이 끊기면 자동으로 다시 연결할 수 있습니다. Socket.IO 클라이언트는 Engine.IO 프로토콜과 호환 모드로 작동합니다.

// pm API를 통한 Postman의 WebSocket 테스트
const ws = new WebSocket("wss://echo.websocket.org");
ws.onmessage = (event) => {
    pm.test("Echo response received", () => {
        pm.expect(event.data).to.eql("Hello");
    });
};

Postman의 Mock 서버와 모니터링

Postman의 Mock 서버는 기존 컬렉션을 기반으로 API 엔드포인트를 에뮬레이션할 수 있게 해줍니다. 백엔드가 아직 준비되지 않았지만 프런트엔드나 모바일 앱이 이미 개발 중일 때 유용합니다. Mock 서버는 올바른 헤더와 상태 코드로 컬렉션의 예제 응답을 반환합니다.

Mock 서버 만들기

Mock 서버는 컬렉션에서 한 번의 클릭으로 생성됩니다: 컬렉션 선택 → Mock Servers → Add a new mock server. Postman은 실제 API 대신 애플리케이션 코드에서 사용할 수 있는 고유한 URL을 생성합니다. 컬렉션의 각 요청에 대해 mock은 저장된 Example Response를 반환하므로 백엔드가 완성되기 전에 UI를 테스트할 수 있습니다.

Postman Monitors를 통한 API 모니터링

Monitors는 일정에 따라(5분마다, 시간마다 또는 하루마다) 컬렉션을 실행하고 API의 가용성과 정확성을 확인합니다. 테스트가 실패하면 모니터가 이메일이나 Slack으로 알림을 보냅니다. 모니터링은 Postman 클라우드에서 작동하며 별도 서버가 필요하지 않고 무료 요금제에서 월 최대 10,000개의 요청을 지원합니다.

// 모니터링용 테스트: 응답 시간 확인
pm.test("Response time < 2000ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
});

보안과 시크릿 관리

Postman은 API 키를 안전하게 다루는 메커니즘을 제공합니다. Secret 유형의 변수는 암호화되며 인터페이스에 표시되지 않습니다. 팀 작업에는 Admin, Editor, Viewer 역할이 있는 Workspace를 사용하세요.

변수 암호화

환경 변수를 만들 때 Secret 유형을 선택하면 모든 인터페이스에서 값이 별표로 숨겨집니다. 시크릿은 공유 시 컬렉션으로 내보내지지 않으며 Newman 로그에도 표시되지 않습니다. 비밀번호와 토큰은 Secret 변수에만 저장하는 것이 좋습니다.

Vault 통합

Postman은 HashiCorp Vault 및 AWS Secrets Manager와의 통합을 지원합니다. Pre-request 스크립트는 외부 저장소에서 시크릿을 동적으로 요청할 수 있어 컬렉션 환경 파일에 민감한 데이터를 저장하지 않을 수 있습니다.

보안과 시크릿 관리

Postman은 API 키를 안전하게 다루는 메커니즘을 제공합니다. Secret 유형의 변수는 암호화되며 인터페이스에 표시되지 않습니다. 팀 작업에는 Admin, Editor, Viewer 역할이 있는 Workspace를 사용하세요.

변수 암호화

환경 변수를 만들 때 Secret 유형을 선택하면 모든 인터페이스에서 값이 별표로 숨겨집니다. 시크릿은 공유 시 컬렉션으로 내보내지지 않으며 Newman 로그에도 표시되지 않습니다. 비밀번호와 토큰은 Secret 변수에만 저장하는 것이 좋습니다.

Vault 통합

Postman은 HashiCorp Vault 및 AWS Secrets Manager와의 통합을 지원합니다. Pre-request 스크립트는 외부 저장소에서 시크릿을 동적으로 요청할 수 있어 컬렉션 환경 파일에 민감한 데이터를 저장하지 않을 수 있습니다.