Postman을 활용한 API 테스트

Postman은 REST API를 테스트하고 관리하기 위한 클라이언트 도구입니다.
백엔드 개발자는 서버가 정상적으로 동작하는지 검증할 수 있고, 프론트엔드 개발자나 QA 엔지니어도 별도의 코드 작성 없이 API를 호출하여 응답 결과를 확인할 수 있습니다.

Postman은 단순한 API 호출 도구를 넘어, 테스트 자동화, 환경 관리, 팀 협업 기능까지 제공하는 API 개발 플랫폼으로 발전했습니다. 

이번 글에서는 Postman의 개념, 핵심 기능, 그리고 실제 개발 과정에서의 활용 방법을 정리합니다.

---

0. Postman 설치

Postman은 데스크톱 애플리케이션 형태로 제공되며, Windows, macOS, Linux 모두에서 사용할 수 있습니다.
아래 공식 사이트에서 운영체제에 맞는 버전을 다운로드할 수 있습니다.

https://www.postman.com/

Postman: The World's Leading API Platform | Sign Up for Free

 

설치 후 실행하면 로그인 또는 회원가입을 요구하지만,
단순한 로컬 테스트 목적이라면 로그인 없이도 “Continue without signing in” 옵션으로 바로 사용할 수 있습니다.

---

1. Postman의 필요성

API를 개발하거나 통합할 때 가장 중요한 단계는 정확한 요청과 응답 검증입니다.
단순히 curl 명령어나 브라우저 요청으로 확인하는 것은 한계가 있으며, 특히 인증이 필요한 API나 복잡한 Body 구조를 가진 요청은 테스트가 어렵습니다.

 

Postman은 다음과 같은 이유로 많이 사용됩니다.

• API 요청을 직관적인 UI에서 구성할 수 있습니다.
• 여러 요청을 하나의 컬렉션으로 관리할 수 있습니다.
• 환경 변수(Environment)를 설정해 개발/운영 서버를 쉽게 전환할 수 있습니다.
• 테스트 스크립트를 작성해 자동화된 검증이 가능합니다.

---

2. Postman의 주요 기능

1) 요청(Request) 생성

Postman에서 새 요청을 만들면 다음 요소를 설정할 수 있습니다.

• Method : GET, POST, PUT, DELETE 등 HTTP 메서드 선택
• URL : 요청을 보낼 엔드포인트 주소
• Headers : 인증 토큰, Content-Type 등 헤더 추가
• Body : JSON, form-data, x-www-form-urlencoded 형식으로 데이터 전송

요청을 실행하면 서버 응답 코드(200, 400, 401 등)와 응답 Body, 헤더를 함께 확인할 수 있습니다.

---

2) 환경(Environment) 관리

Postman은 개발, 스테이징, 운영 환경별로 다른 URL이나 토큰을 변수로 관리할 수 있습니다.

예를 들어,

{{base_url}}/api/users

로 요청을 정의하고, base_url을 환경 변수로 지정하면
서버 전환 시 URL을 일일이 수정할 필요가 없습니다.

환경 파일에는 다음과 같은 변수를 정의할 수 있습니다.

• base_url : 서버 주소
• access_token : 인증 토큰

user_id : 테스트용 사용자 ID

---

3) 컬렉션(Collection) 관리

컬렉션은 여러 개의 API 요청을 그룹화한 구조입니다.
하나의 프로젝트 단위로 관련된 API를 묶어 관리할 수 있으며, 요청 순서에 따라 자동 실행하거나 팀원과 공유할 수 있습니다.

 

예시 구조:

User Collection
 ┣ GET /api/users
 ┣ POST /api/users
 ┗ DELETE /api/users/{id}

컬렉션 단위로 Export하여 다른 개발자와 공유할 수도 있고,
버전 관리 도구(Git)로 함께 관리하기에도 용이합니다.

 

---

4) 테스트 스크립트

Postman은 요청 전후에 실행할 JavaScript 기반의 테스트 코드를 작성할 수 있습니다.
응답 상태 코드나 필드 값을 자동으로 검증하여 테스트 자동화를 구현할 수 있습니다.

 

예시:

pm.test("응답 코드가 200이어야 함", function () {
    pm.response.to.have.status(200);
});

pm.test("응답 Body에 name 필드가 존재해야 함", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property("name");
});

이 스크립트는 API 요청 후 자동으로 실행되어 결과를 Pass/Fail 형태로 표시합니다.
테스트 케이스를 여러 개 만들어 API의 동작을 자동 검증하는 것도 가능합니다.

 

---

5) Authorization (인증 관리)

Postman은 다양한 인증 방식을 지원합니다.

• Bearer Token
• Basic Auth
• OAuth 2.0
• API Key

각 요청마다 개별로 지정할 수도 있고, 컬렉션 전체에 공통으로 설정할 수도 있습니다.
예를 들어 JWT를 사용하는 경우, Header에 자동으로 토큰이 추가되도록 설정할 수 있습니다.

Authorization → Type: Bearer Token  
Token → {{access_token}}

 

---

6) 테스트 자동화 및 CI/CD 연동

Postman은 단독 실행 외에도 Newman이라는 CLI(Command Line Interface) 도구를 통해 테스트를 자동화할 수 있습니다.
Newman을 CI/CD 파이프라인(Jenkins, GitHub Actions 등)에 통합하면
코드가 배포되기 전 API 테스트를 자동으로 수행할 수 있습니다.

예시 (터미널 실행):

newman run collection.json -e dev_environment.json

이 명령어는 지정된 컬렉션을 Postman 없이 실행하고 결과를 콘솔로 출력합니다.
빌드 과정에 포함시키면 배포 전 API 검증을 자동화할 수 있습니다.

 

---

3. Postman 사용 시 주의사항

1. 환경 변수 보안
   Access Token, API Key 등의 민감한 정보를 공유된 환경 파일에 저장하지 않습니다.
   Postman의 “Team Workspace”를 사용하는 경우, 변수의 secret 속성을 활성화해 민감 정보를 보호합니다.
2. 컬렉션 버전 관리
   API가 자주 변경되는 프로젝트에서는 컬렉션의 버전을 구분해 관리해야 합니다.
   예: v1_User_Apis, v2_User_Apis
3. 요청 이력 정리
   Postman은 요청 이력을 자동으로 저장하지만, 불필요한 요청이 많아지면 관리가 어려워집니다.
   프로젝트별로 컬렉션을 정리해 유지보수성을 높이는 것이 좋습니다.

---

4. 결론

Postman은 API 테스트를 위한 사실상 표준 도구로 자리 잡았습니다.
UI 기반의 직관적인 요청 관리부터 자동화 테스트, CI/CD 연동까지 지원하기 때문에
개발자뿐 아니라 QA, 기획자도 동일한 API 환경에서 테스트를 수행할 수 있습니다.

특히 Swagger와 함께 사용하면
Swagger로 API 명세를 자동 생성하고, Postman으로 실제 요청을 검증하는 완전한 API 워크플로우를 구성할 수 있습니다.

정리하자면,

• Swagger → API 문서 자동화 및 시각화
• Postman → API 요청 테스트 및 자동화

두 도구를 함께 사용하면 API 개발의 품질과 효율성을 크게 높일 수 있습니다.