현대 소프트웨어 개발에서 API(Application Programming Interface)는 애플리케이션 간의 상호작용을 가능하게 하는 핵심적인 요소입니다. 마이크로서비스 아키텍처의 확산과 함께 API의 복잡성은 증가하고 있으며, 이에 따라 API 개발 및 테스트의 효율성은 프로젝트 성공에 결정적인 영향을 미칩니다. 개발자는 수많은 API 엔드포인트를 관리하고, 다양한 환경에서 테스트하며, 일관된 품질을 유지해야 하는 과제에 직면합니다. 이러한 복잡성을 효과적으로 관리하고 생산성을 극대화하기 위한 솔루션 중 하나가 바로 Postman입니다.
Postman은 API 요청 생성, 테스트, 문서화, 공유 등 API 라이프사이클 전반을 지원하는 강력한 도구입니다. 단순히 API 요청을 보내는 것을 넘어, 컬렉션(Collections)을 통한 체계적인 관리, 환경 변수(Environment Variables)를 활용한 유연한 설정, 그리고 스크립트(Scripts) 기반의 자동화된 테스트 및 워크플로우 구축 기능을 제공합니다. 본 가이드에서는 Postman의 핵심 기능을 깊이 있게 탐구하여, API 개발 및 테스트 과정을 자동화하고 효율화하는 실질적인 방안을 제시하고자 합니다.
📑 목차
- Postman 컬렉션으로 API 요청 체계화하기
- 컬렉션의 구조와 이점
- 컬렉션 생성 및 요청 추가 예시
- 환경 변수를 활용한 유연한 API 관리
- 환경 변수의 필요성과 종류
- 환경 변수 설정 및 활용 예시
- 테스트 및 워크플로우 자동화를 위한 스크립트 활용
- Pre-request Script: 요청 전 처리 로직 구현
- Test Script: 응답 검증 및 후처리 로직 구현
- Postman 고급 활용 전략
- Collection Runner를 활용한 배치 테스트
- Newman을 활용한 CI/CD 파이프라인 통합
- Mock 서버를 활용한 병렬 개발 및 테스트
- Collection Runner와 Newman 비교
- 결론: Postman과 함께하는 효율적인 API 개발
Image by RiaanMarais on Pixabay
Postman 컬렉션으로 API 요청 체계화하기
수많은 API 요청을 개별적으로 관리하는 것은 비효율적이며 오류를 유발할 가능성이 높습니다. Postman 컬렉션은 관련 API 요청들을 논리적으로 그룹화하고 체계적으로 관리할 수 있도록 돕는 핵심 기능입니다. 이는 API 개발 및 테스트 프로세스의 효율성과 일관성을 크게 향상시킬 수 있습니다.
컬렉션의 구조와 이점
컬렉션은 단순한 폴더 구조를 넘어섭니다. 각 컬렉션은 여러 개의 폴더를 포함할 수 있으며, 각 폴더 안에는 특정 기능을 수행하는 API 요청들이 그룹화됩니다. 예를 들어, 사용자 관리 API, 제품 관리 API, 결제 API 등으로 컬렉션 내 폴더를 구성할 수 있습니다. 이러한 구조는 다음과 같은 이점을 제공합니다.
- 조직화 및 관리 용이성: 복잡한 프로젝트의 API를 기능별, 모듈별로 명확하게 분류하여 관리할 수 있습니다. 이는 개발자가 필요한 API 요청을 신속하게 찾아 사용할 수 있도록 돕습니다.
- 재사용성 증대: 공통적으로 사용되는 요청 헤더, 인증 정보, 스크립트 등을 컬렉션 또는 폴더 레벨에서 설정함으로써, 개별 요청마다 반복적으로 설정할 필요 없이 재사용성을 높일 수 있습니다.
- 협업 및 공유 촉진: 컬렉션은 팀원 간에 쉽게 공유될 수 있어, 모든 팀원이 동일한 API 정의와 테스트 케이스를 기반으로 작업할 수 있도록 지원합니다. 이는 팀 전체의 일관성을 유지하고 개발 과정을 가속화합니다.
- 문서화의 기반: 컬렉션 자체에 대한 설명, 각 요청에 대한 상세 설명, 예시 응답 등을 포함하여 API 문서화의 기반으로 활용될 수 있습니다. Postman은 컬렉션을 기반으로 API 문서를 자동으로 생성하는 기능도 제공합니다.
컬렉션 생성 및 요청 추가 예시
새로운 컬렉션을 생성하고 그 안에 API 요청을 추가하는 과정은 직관적입니다. Postman 사이드바에서 'New' 버튼을 클릭한 후 'Collection'을 선택하여 새로운 컬렉션을 생성합니다. 생성된 컬렉션에 마우스를 올리면 나타나는 '...' 메뉴에서 'Add Request'를 선택하여 요청을 추가할 수 있습니다.
// 예시: 사용자 정보 조회 API 요청 (GET /users/{id})
// 컬렉션: My_API_Project
// 폴더: User Management
// 1. 컬렉션 생성: "My_API_Project"
// 2. 폴더 생성: "User Management" (My_API_Project 하위)
// 3. 요청 추가: "Get User by ID" (User Management 폴더 하위)
// - Method: GET
// - URL: {{base_url}}/users/{{user_id}}
// - Headers:
// - Content-Type: application/json
// - Authorization: Bearer {{access_token}}
// - Description: 특정 사용자 ID로 사용자 정보를 조회합니다.
이와 같이 구성된 컬렉션은 프로젝트의 API 구조를 명확하게 반영하며, 필요한 API 요청을 손쉽게 찾고 실행할 수 있도록 지원합니다.
환경 변수를 활용한 유연한 API 관리
API 개발 및 테스트 과정에서 가장 흔히 마주하는 문제 중 하나는 개발, 스테이징, 운영 등 다양한 환경에 따라 API 엔드포인트나 인증 정보가 달라지는 경우입니다. 이러한 정보를 하드코딩하면 환경 변경 시마다 요청을 수정해야 하는 번거로움이 발생하며, 이는 오류 발생 가능성을 높이고 생산성을 저하시킵니다. Postman 환경 변수는 이러한 문제를 해결하고 API 관리에 유연성을 부여하는 강력한 기능입니다.
환경 변수의 필요성과 종류
환경 변수는 API 요청 내에서 동적으로 변경될 수 있는 값을 저장하는 데 사용됩니다. 예를 들어, 기본 URL, API 키, 인증 토큰, 사용자 ID 등이 환경 변수로 관리될 수 있습니다. Postman은 크게 두 가지 유형의 변수를 제공합니다.
- 환경 변수(Environment Variables): 특정 환경(예: 개발, 스테이징, 운영)에 국한되어 사용되는 변수입니다. 각 환경별로 동일한 이름의 변수에 다른 값을 할당할 수 있습니다.
- 글로벌 변수(Global Variables): Postman 워크스페이스 내의 모든 컬렉션과 요청에서 접근 가능한 변수입니다. 환경에 관계없이 전역적으로 사용되어야 하는 값(예: 모든 API에 공통으로 적용되는 버전 정보)에 적합합니다.
이 외에도 컬렉션 변수, 데이터 변수, 로컬 변수 등이 존재하여 다양한 스코프에서 변수를 활용할 수 있습니다. 일반적으로는 환경 변수를 활용하여 환경별 설정을 관리하는 것이 가장 보편적입니다.
환경 변수 설정 및 활용 예시
환경 변수를 설정하려면 Postman 화면 우측 상단의 환경 선택 드롭다운 메뉴에서 'Manage Environments'를 클릭합니다. 여기서 새로운 환경을 추가하고 변수 이름과 초기값, 현재값을 지정할 수 있습니다. 변수는 `{{변수이름}}` 형태로 API 요청 내에서 참조됩니다.
// 예시: 개발 및 운영 환경 변수 설정
// 환경 1: Development
// - base_url: http://dev.api.example.com
// - access_token: dev_jwt_token_123
// - user_id: 101
// 환경 2: Production
// - base_url: https://api.example.com
// - access_token: prod_jwt_token_xyz
// - user_id: 5001
// API 요청 예시 (환경 변수 활용)
// GET {{base_url}}/users/{{user_id}}
// Headers:
// - Authorization: Bearer {{access_token}}
위와 같이 설정하면, 개발 환경을 선택했을 때는 `http://dev.api.example.com/users/101`로, 운영 환경을 선택했을 때는 `https://api.example.com/users/5001`로 요청이 전송됩니다. 이는 민감한 정보(예: API 키)를 요청 본문이나 URL에 직접 노출하지 않고 안전하게 관리하는 데에도 매우 효과적입니다.
Image by 5851928 on Pixabay
테스트 및 워크플로우 자동화를 위한 스크립트 활용
Postman은 단순한 API 요청 도구를 넘어, JavaScript 기반의 스크립트 기능을 통해 API 테스트를 자동화하고 복잡한 워크플로우를 구축할 수 있는 강력한 플랫폼을 제공합니다. 스크립트는 크게 요청 전 실행되는 Pre-request Script와 응답 후 실행되는 Test Script로 나뉩니다.
Pre-request Script: 요청 전 처리 로직 구현
Pre-request Script는 API 요청이 전송되기 전에 실행되는 스크립트입니다. 이 스크립트를 활용하여 다음과 같은 작업을 수행할 수 있습니다.
- 동적 데이터 생성: 요청 본문에 포함될 타임스탬프, UUID 등 동적인 데이터를 생성하여 환경 변수에 저장하고 요청에서 참조할 수 있습니다.
- 인증 토큰 갱신: 만료된 인증 토큰을 자동으로 갱신하고, 갱신된 토큰을 환경 변수에 저장하여 다음 요청에 사용할 수 있습니다.
- 요청 데이터 전처리: 특정 조건에 따라 요청 파라미터나 헤더를 동적으로 변경하는 등의 전처리 로직을 구현할 수 있습니다.
// 예시: JWT 토큰 자동 갱신 (Pre-request Script)
// 이 스크립트는 요청 전에 실행되어, 만료된 토큰이 있다면 새 토큰을 요청하여 환경 변수에 저장합니다.
// 실제 JWT 토큰 갱신 로직은 더 복잡할 수 있습니다.
if (pm.environment.get("access_token_expiry") && Date.now() > pm.environment.get("access_token_expiry")) {
// 토큰 갱신 API 호출 로직 (예시)
pm.sendRequest({
url: '{{base_url}}/auth/refresh',
method: 'POST',
header: 'Content-Type:application/json',
body: {
mode: 'raw',
raw: JSON.stringify({
"refreshToken": pm.environment.get("refresh_token")
})
}
}, function (err, res) {
if (err) {
console.log(err);
} else {
const responseJson = res.json();
pm.environment.set("access_token", responseJson.accessToken);
pm.environment.set("access_token_expiry", Date.now() + responseJson.expiresIn * 1000); // 초 단위 expiresIn을 밀리초로 변환
console.log("Access token refreshed.");
}
});
}
Test Script: 응답 검증 및 후처리 로직 구현
Test Script는 API 요청이 전송되고 서버로부터 응답을 받은 후에 실행됩니다. 이 스크립트의 주요 목적은 응답의 유효성을 검증하고, 다음 요청에 필요한 정보를 추출하는 것입니다.
- 응답 상태 코드 검증: 응답이 예상하는 HTTP 상태 코드(예: 200 OK, 201 Created)를 반환하는지 확인합니다.
- 응답 데이터 검증: 응답 본문에 특정 필드가 포함되어 있는지, 그 값이 예상과 일치하는지 등을 검증합니다.
- 스키마 유효성 검사: 응답 본문이 정의된 JSON 스키마에 부합하는지 검사합니다.
- 다음 요청을 위한 데이터 추출: 응답 본문에서 특정 값을 추출하여 환경 변수에 저장하고, 이를 후속 API 요청에서 사용할 수 있도록 합니다. 이는 API 체이닝(Chaining)을 구현하는 데 필수적입니다.
// 예시: 사용자 생성 API 응답 검증 및 ID 추출 (Test Script)
pm.test("Status code is 201 Created", function () {
pm.response.to.have.status(201);
});
pm.test("Response body has 'id' field", function () {
const responseJson = pm.response.json();
pm.expect(responseJson.id).to.exist;
pm.expect(typeof responseJson.id).to.equal('number');
});
pm.test("Response body has 'name' field with expected value", function () {
const responseJson = pm.response.json();
pm.expect(responseJson.name).to.equal("새로운 사용자");
});
// 다음 요청을 위해 생성된 사용자 ID를 환경 변수에 저장
const responseJson = pm.response.json();
if (responseJson && responseJson.id) {
pm.environment.set("newly_created_user_id", responseJson.id);
console.log("Newly created user ID saved: " + responseJson.id);
}
이처럼 스크립트를 활용하면 반복적인 수동 테스트 과정을 자동화하고, API의 기능적 정확성을 지속적으로 검증할 수 있습니다. 이는 개발 주기를 단축하고 소프트웨어 품질을 향상시키는 데 크게 기여합니다.
Image by frankvouffa on Pixabay
Postman 고급 활용 전략
Postman은 컬렉션, 환경 변수, 스크립트라는 기본 기능 외에도, API 개발 및 테스트 효율성을 극대화할 수 있는 다양한 고급 기능을 제공합니다. 이러한 기능들을 활용하면 더욱 견고하고 자동화된 API 워크플로우를 구축할 수 있습니다.
Collection Runner를 활용한 배치 테스트
Collection Runner는 컬렉션 내의 모든 요청을 한 번에 순차적으로 실행하고, 각 요청의 테스트 스크립트 결과를 종합하여 보여주는 기능입니다. 이는 회귀 테스트(Regression Test)나 통합 테스트(Integration Test)를 수행하는 데 매우 유용합니다.
- 순차적 실행: 컬렉션에 정의된 순서대로 요청들을 실행하며, Pre-request 및 Test 스크립트도 각 요청에 맞춰 실행됩니다.
- 데이터 파일 연동: CSV 또는 JSON 파일로부터 데이터를 읽어와 각 요청에 동적으로 적용할 수 있습니다. 예를 들어, 수백 개의 사용자 데이터를 사용하여 사용자 생성 API를 테스트하는 시나리오에 활용될 수 있습니다.
- 테스트 결과 보고: 모든 테스트 케이스의 성공/실패 여부를 시각적으로 명확하게 보고하여, API의 전반적인 상태를 한눈에 파악할 수 있도록 돕습니다.
// Collection Runner 실행 시 데이터 파일 (data.csv) 예시
// user_id, user_name, user_email
// 1, "Alice", "alice@example.com"
// 2, "Bob", "bob@example.com"
// 요청 URL: {{base_url}}/users/{{user_id}}
// 요청 Body: { "name": "{{user_name}}", "email": "{{user_email}}" }
// Collection Runner는 각 행의 데이터를 {{user_id}}, {{user_name}}, {{user_email}} 변수에 바인딩하여 요청을 실행합니다.
Newman을 활용한 CI/CD 파이프라인 통합
Newman은 Postman 컬렉션을 명령줄에서 실행할 수 있게 해주는 CLI(Command Line Interface) 도구입니다. 이를 통해 CI/CD(Continuous Integration/Continuous Deployment) 파이프라인에 Postman API 테스트를 통합하여, 코드 변경이 발생할 때마다 자동으로 API 테스트를 수행할 수 있습니다.
- 자동화된 테스트: Jenkins, GitLab CI, GitHub Actions 등 CI/CD 툴에서 Newman을 호출하여 API 테스트를 자동화하고, 빌드 및 배포 과정의 일부로 포함시킬 수 있습니다.
- 확장성: 다양한 보고서 형식(HTML, JSON, JUnit XML 등)을 지원하여, 테스트 결과를 시각화하고 다른 시스템과 연동할 수 있습니다.
- headless 실행: GUI 없이 서버 환경에서 Postman 테스트를 실행할 수 있어, 서버 리소스 활용에 효율적입니다.
# Newman CLI 실행 예시
# Postman 컬렉션 파일과 환경 파일 경로를 지정하여 실행
newman run my_collection.json -e my_environment.json -r cli,htmlextra --reporter-htmlextra-export output/report.html
Mock 서버를 활용한 병렬 개발 및 테스트
Postman Mock Server는 실제 백엔드 API가 아직 개발되지 않았거나 접근하기 어려운 상황에서, 미리 정의된 응답을 반환하는 가상의 서버를 제공합니다. 이는 프론트엔드 개발자가 백엔드 개발과 독립적으로 작업을 진행하고, 테스트 환경을 구축하는 데 필수적인 도구입니다.
- 프론트엔드-백엔드 병렬 개발: 백엔드 개발이 완료될 때까지 기다릴 필요 없이 프론트엔드 개발자가 Mock 서버를 통해 API 응답을 시뮬레이션하며 개발을 진행할 수 있습니다.
- 독립적인 테스트: 백엔드 시스템의 상태나 외부 서비스의 가용성에 관계없이 API 클라이언트의 동작을 테스트할 수 있습니다.
- 에러 시나리오 테스트: 다양한 에러 응답 시나리오(예: 400 Bad Request, 500 Internal Server Error)를 Mock 서버에서 쉽게 구성하여 클라이언트의 에러 처리 로직을 검증할 수 있습니다.
Postman에서 요청을 예시(Example)로 저장하고, 이를 기반으로 Mock 서버를 생성하면 해당 예시 응답을 반환하는 Mock API 엔드포인트가 자동으로 생성됩니다.
Collection Runner와 Newman 비교
Collection Runner와 Newman은 모두 컬렉션 내의 요청들을 실행하는 기능을 제공하지만, 사용 목적과 환경에 차이가 있습니다.
| 특징 | Collection Runner | Newman |
|---|---|---|
| 실행 환경 | Postman GUI (데스크톱 앱) | 명령줄 (CLI) |
| 주요 사용 목적 | 수동 배치 테스트, 개발 중 테스트, 시각적 결과 확인 | CI/CD 파이프라인 통합, 자동화된 회귀 테스트, 서버 환경 실행 |
| 데이터 파일 지원 | CSV, JSON 파일 지원 | CSV, JSON 파일 지원 |
| 보고서 형식 | Postman 앱 내 시각적 보고서 | CLI 출력, HTML, JSON, JUnit XML 등 다양한 형식 |
| 자동화 수준 | 수동 실행 기반의 배치 자동화 | 완전 자동화된 스케줄링 및 통합 가능 |
이러한 고급 기능들을 적절히 활용함으로써, Postman은 단순한 API 클라이언트를 넘어 API 라이프사이클 전반을 관리하고 자동화하는 통합 플랫폼으로서의 역할을 수행할 수 있습니다.
결론: Postman과 함께하는 효율적인 API 개발
Postman은 API 개발 및 테스트 과정에서 발생하는 수많은 과제를 해결하고 개발자의 생산성을 극대화하는 데 필수적인 도구로 자리매김했습니다. Postman 컬렉션을 통해 API 요청을 체계적으로 조직하고 관리할 수 있으며, 환경 변수를 활용하여 다양한 개발 환경에 유연하게 대응할 수 있습니다. 또한, Pre-request 및 Test 스크립트를 이용한 자동화된 테스트는 API의 안정성과 신뢰성을 보장하고, 반복적인 수동 작업을 줄여줍니다.
나아가 Collection Runner를 통한 배치 테스트, Newman을 활용한 CI/CD 파이프라인 통합, Mock 서버를 이용한 병렬 개발은 API 개발 워크플로우를 더욱 견고하고 효율적으로 만듭니다. 이러한 Postman의 강력한 기능들을 숙달하고 프로젝트에 적극적으로 적용함으로써, 개발 팀은 API 개발 주기를 단축하고 고품질의 API를 지속적으로 제공할 수 있습니다.
API 기반의 서비스가 더욱 중요해지는 시점에서, Postman의 모든 기능을 마스터하는 것은 개발자로서의 역량을 강화하고 성공적인 프로젝트를 이끄는 데 핵심적인 역량이 될 것으로 판단됩니다. 본 가이드가 Postman을 활용한 API 개발 및 테스트 자동화 여정에 도움이 되기를 바랍니다.
Postman 활용에 대한 궁금증이나 여러분의 경험을 댓글로 공유해주세요. 함께 더 나은 API 개발 문화를 만들어갈 수 있습니다.