[Postman] Usage

공식 문서: Postman quick start

Postman은 HTTP API를 만들고, 호출하고, 테스트하고, 문서화하는 데 사용하는 API platform이다. 처음에는 단순히 API 요청을 보내는 도구처럼 보이지만, collection, environment, test script를 함께 쓰면 반복 가능한 API 테스트 도구가 된다.

이미지 출처: Postman Docs - Quick start

Postman에서 가장 기본이 되는 구성은 다음과 같다.

첫 요청 보내기

가장 단순한 GET request는 다음 요소로 구성된다.

Method: GET
URL: https://api.example.com/users

Postman에서는 method를 선택하고 URL을 입력한 뒤 Send를 누르면 된다. 응답 영역에서는 다음을 확인한다.

예를 들어 정상 조회라면 보통 200 OK를 기대한다.

{
  "id": 1,
  "name": "Alice"
}

HTTP Method

API 테스트에서 먼저 확인할 것은 method이다.

예를 들어 사용자 생성 API는 보통 POST를 사용한다.

POST https://api.example.com/users

사용자 조회 API는 GET을 사용한다.

GET https://api.example.com/users/1

Method가 틀리면 서버 route가 맞지 않아 404, 405 Method Not Allowed 같은 응답이 나올 수 있다.

Query Params

Query parameter는 URL 뒤에 붙는 key-value 값이다.

GET /users?page=1&limit=20&sort=created_at

Postman에서는 Params tab에 key와 value를 입력하면 URL에 자동으로 붙는다.

Query param은 주로 filtering, pagination, sorting에 사용한다.

GET /posts?tag=aws&page=2

Headers

Header는 request metadata이다. 인증, content type, cache control 등에 사용된다.

대표적인 header는 다음과 같다.

JSON body를 보내려면 보통 다음 header가 필요하다.

Content-Type: application/json

Bearer token 인증은 다음 형태이다.

Authorization: Bearer <access-token>

Postman의 Authorization tab을 쓰면 직접 header를 쓰지 않아도 자동으로 Authorization header를 구성할 수 있다.

Body

POST, PUT, PATCH request는 body를 함께 보내는 경우가 많다. JSON API에서는 Body -> raw -> JSON을 선택하고 JSON을 입력한다.

예를 들어 사용자 생성 request는 다음과 같다.

POST /users
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com"
}

서버에서는 이 body를 parsing해서 resource를 생성한다. Body 형식과 Content-Type이 맞지 않으면 서버가 request를 해석하지 못할 수 있다.

Collection

Collection은 관련 request를 묶는 단위이다. 프로젝트별 API를 collection으로 정리하면 반복 테스트가 쉬워진다.

예를 들어 blog API collection은 다음처럼 구성할 수 있다.

Blog API
  Auth
    POST Login
    POST Refresh Token
  Posts
    GET List Posts
    GET Get Post
    POST Create Post
    PATCH Update Post
    DELETE Delete Post

Collection을 쓰면 다음 장점이 있다.

Environment Variables

Environment는 request에서 사용할 변수를 모아둔 것이다. 개발/스테이징/운영 API 주소가 다를 때 유용하다.

예를 들어 environment에 다음 변수를 둔다.

Request URL은 다음처럼 쓴다.

{{base_url}}/users

Header도 변수로 처리할 수 있다.

Authorization: Bearer {{access_token}}

이렇게 하면 request 자체는 바꾸지 않고 environment만 바꿔 여러 서버에 같은 API 호출을 보낼 수 있다.

Tests

Postman의 Tests tab에서는 JavaScript로 response를 검증할 수 있다. 예를 들어 status code가 200인지 확인하려면 다음처럼 쓴다.

pm.test('status is 200', function () {
  pm.response.to.have.status(200)
})

JSON response의 값을 확인할 수도 있다.

pm.test('response has user id', function () {
  const data = pm.response.json()
  pm.expect(data).to.have.property('id')
})

Login API response에서 token을 environment variable에 저장하는 것도 가능하다.

const data = pm.response.json()
pm.environment.set('access_token', data.accessToken)

이렇게 하면 다음 request에서 {{access_token}}을 사용할 수 있다.

Pre-request Script

Pre-request script는 request를 보내기 전에 실행된다. timestamp, signature, random value를 만들 때 유용하다.

예를 들어 timestamp 변수를 설정할 수 있다.

pm.environment.set('timestamp', Date.now().toString())

이후 request header나 body에서 사용할 수 있다.

X-Request-Time: {{timestamp}}

인증 signature를 매번 계산해야 하는 API라면 pre-request script가 도움이 된다.

Collection Runner

Collection Runner는 collection 안의 request를 순서대로 실행한다. API smoke test나 간단한 regression test에 사용할 수 있다.

예를 들어 다음 흐름을 자동으로 돌릴 수 있다.

1. Login
2. Create Post
3. Get Post
4. Update Post
5. Delete Post

각 request의 Tests가 통과하는지 확인하면 API가 기본적으로 살아 있는지 빠르게 검증할 수 있다.

자주 하는 실수

Postman을 사용할 때 자주 생기는 문제는 다음과 같다.

특히 environment를 잘못 선택하면 운영 API에 테스트 request를 보내는 실수를 할 수 있다. 삭제/수정 API를 테스트할 때는 항상 environment와 URL을 확인해야 한다.

좋은 Collection 구조

좋은 collection은 API 사용 흐름을 보여준다. 단순히 request를 저장하는 데서 끝나지 않고, 이름과 folder 구조만 봐도 API가 이해되어야 한다.

Service API
  00 Health
  01 Auth
  02 Users
  03 Posts
  04 Admin

Request 이름도 구체적으로 쓰는 것이 좋다.

GET List Users
GET Get User by ID
POST Create User
PATCH Update User Profile
DELETE Delete User

이렇게 하면 Postman collection 자체가 팀의 API 사용 예제가 된다.

정리

Postman의 기본 사용법은 request를 만들고 response를 확인하는 것이다. 하지만 제대로 쓰려면 collection, environment, test를 함께 써야 한다.

핵심 흐름은 다음이다.

Request를 만든다.
Params, headers, body를 설정한다.
Environment variable로 base URL과 token을 관리한다.
Response를 확인한다.
Tests로 기대 결과를 검증한다.
Collection에 저장해 반복 실행한다.

Postman은 단순 API 호출 도구가 아니라, API를 반복 가능하게 실험하고 문서화하고 검증하는 도구로 이해하는 것이 좋다.