ETC

Postman Mock 서버 구성

알쓸개잡 2025. 10. 17.

API 개발을 하다 보면 프런트엔드와 백엔드 개발 속도가 맞지 않는 경우가 있다. 백엔드 API가 개발 중이거나, 외부 서비스와의 연동이 지연되는 경우 프런트엔드 개발자 혹은 클라이언트 개발자는 테스트할 데이터나 응답 구조가 없어 테스트가 어려운 경우가 있다. 이런 경우 postman의 mock 서버 구성을 통해서 API 요청에 대한 확인을 할 수 있다. 이번 포스팅에서는 postman을 이용하여 mock 서버를 구성하는 방법에 대해서 정리하고자 한다.

Postman Mock Server란

Mock Server는 실제 서버 없이도 API 요청에 대해 미리 정의한 Example 응답을 반환하는 Postman의 기능이다. 즉, 백엔드가 아직 개발되지 않았을 때도 프런트엔드나 테스트 코드가 "API가 이미 존재하는 것처럼" 작동하도록 해주는 가짜 서버를 의미한다.

Postman Mock Server 생성

이 예시에서는 collection을 미리 생성한 뒤 Mock Server 생성시 미리 생성한 collection을 지정하는 방법으로 진행한다.

(Mock Server 생성 시 'An existing collection' 선택)

참고로 Mock Server 생성 시 'Create a new collection'을 선택하면 Mock Server 이름과 동일한 collection을 자동으로 생성해 준다.

Postman의 Mock 서버를 통해 미리 정의한 응답을 위해서 Example을 생성해야 한다. Example은 Postman의 Request로부터 생성할 수 있다.

컬렉션 생성 (이미 존재하는 컬렉션을 사용할 수도 있다)
요청 생성
요청에서 Add Example 기능을 통해 Example을 생성할 수 있다.

postman 요청에서 콘텍스트 메뉴 혹은 '...'을 통해서 Add Example을 선택할 수 있다.

이 예에서는 'mock server'이름의 collection을 생성하였다.

Example 생성

요청에 대한 Example을 생성하여 해당 요청을 mock 서버를 통해 호출하였을 때 Example에 정의한 응답 코드와 body payload를 미리 정의할 수 있다.

일반적인 request 생성과 같이 method와 URL을 지정한다. URL은 mock서버 호스트 다음에 붙는 URI를 지정한다.

Body 부분은 Mock Server가 응답할 body payload를 정의한다. Status Code 부분은 Mock Server가 응답할 상태 코드를 정의한다.

Mock Server를 생성하면 Mock Server 접속 정보를 알려주는데 위 Example에서는

<mock server 접속 정보>/user/{{userId}} 형식의 URL이 하나의 Mock Server API 엔드포인트가 된다.

Example 요청의 URL 경로(path)에 사용된 변수 중 컬렉션이나 환경(Environment)에 존재하지 않는 변수는 와일드카드 변수로 간주된다. 즉, Postman이 모르는 값에 대해서는 Path 매칭 시 어떤 값이 와도 허용하는 동적 세그먼트로 취급한다.

위 예에서 {{userId}}가 Environment에 등록되지 않았다면 와일드카드로 인식하여 호출시 /user/1, /user/2, /user/999 모두 경로 매칭이 된다.

또한 응답 body에 정의한 {{userId}}는 경로에서 캡처된 {{userId}} 값을 사용한다.

예를 들어 /user/2를 요청하면 'id: 2', /user/999를 요청하면 'id: 999'로 응답한다.

Mock Server 생성

Mock Server를 생성해보자. Mock Server는 좌측 메뉴 목록에서 Mock servers를 선택 후 '+' 버튼으로 생성할 수 있다.

아래는 Mock Server 생성을 위한 설정 화면이다.

Mock Server 이름을 설정하고 연결할 collection을 지정한다. Create a new collection은 연결할 컬렉션을 직접 생성해 주어야 한다. 경험상 collection > request > example을 생성한 후에 Mock Server 생성 시 'An existing collection'으로 미리 만들어 둔 collection을 연결하는 것이 직관적이었던 것 같다. Environment 항목에서 미리 생성한 Environment가 있다면 해당 Environment를 지정 가능하다.

'Save the mock server URL as an new environment variable'을 체크하면 Mock Server URL을 Mock Server이름과 동일한 별도의 Environment를 생성하여 'url' 이름으로 저장한다. collection에서 Mock Server URL을 직접 입력할 필요 없이 {{url}} 변수를 사용하면 편하므로 체크를 하는 것이 좋다.

'Save the mock server URL as an new environment variable 체크시 Environment 생성'

'Make mock server private'는 Mock Server API를 호출할 때 x-api-key 헤더를 지정하여 호출해야 한다.

Postman API Key를 생성하는 방법은 https://learning.postman.com/docs/developer/postman-api/authentication/ 링크 참고

Mock Server를 생성하면 다음과 같은 정보를 만날 수 있다.

Mock Server 타입과 연결된 collection 정보 참고하는 Environment 정보를 확인 할 수 있다.

'No mock server calls yet' 영역에는 Mock Server로 접수된 요청과 응답에 대한 히스토리를 보여준다.

Mock Server API 호출

위 예시에서 Mock Server이름은 'mock server for test'이고 Mock Server URL은

https://d4879412-6 baf-4610-8fe5-08d28528879f.mock.pstmn.io이다.

그리고 Environment에 'mock server for test' 이름으로 url 변수에 https://d4879412-6 baf-4610-8fe5-08d28528879f.mock.pstmn.io URL이 등록되어 있다.

Mock Server URL을 직접 curl 명령으로 지정해서 호출해도 되고 postman의 request에서 API를 호출하듯이 호출해도 된다.

postman의 request에서 API를 호출하듯이 호출하는 경우에는 {{url}} 변수를 사용하여 손쉽게 호출할 수 있다. 우선 {{url}} 변수를 사용하기 위해서 'mock server' collection에 'mock server for test' Environment를 연결한다.

Environment를 연결하는 방법은 'mock server' collection Overview 설정에서 우측의 'Pinned Environments' 항목의 + 버튼으로 Environment를 연결할 수 있다.

처음 부분에 생성했던 'mock server' collection에 'get user' 이름의 request를 생성했었는데 이 request를 설정해서 Mock Server API를 호출해 보자.

등록한 Environment로 인해 {{url}}에는 Mock Server URL로 사용된다. 'Example 생성' 파트에서 정의한 Example의 상태 코드와 body payload를 응답하는 것을 확인할 수 있다.

물론 다음과 같이 curl 명령을 통해서 호출하는 것도 가능하다.

 ~/ curl https://d4879412-6baf-4610-8fe5-08d28528879f.mock.pstmn.io/user/1 | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    97  100    97    0     0    100      0 --:--:-- --:--:-- --:--:--   100
{
  "id": 1,
  "name": "아무개",
  "email": "noname@example.com",
  "phone": "010-1234-5678"
}

POST를 위한 request와 example도 작성해 보자.

먼저 이름만 정의한 request를 만들고 request에 대한 example를 생성한다.

Mock Server에서 어떤 API를 호출하는 매칭은 Path 기반으로 하기 때문에 request에 대한 body를 지정하지 않아도 된다. 하지만 정의한 request body가 일치하는 경우에만 정상적으로 응답받도록 하고 싶은 경우에는 request에 대한 body를 지정해야 한다.

방법은 요청 헤더에 'x-mock-match-request-body: true'를 설정하는 것인데, 이 경우 요청 body와 example에서 정의한 요청 body가 일치하는 경우에만 응답한다.

먼저 x-mock-match-request-body를 지정하지 않은 경우는 다음과 같이 응답한다.

 ~/ curl -X POST https://d4879412-6baf-4610-8fe5-08d28528879f.mock.pstmn.io/user
{
  "id": 100,
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "010-1234-5678"
}

method와 URL 경로가 일치하므로 example에서 정의한 body payload가 정상적으로 응답한다.

x-mock-match-request-body 헤더를 지정해서 호출해 보자.

 ~/ curl -X POST https://d4879412-6baf-4610-8fe5-08d28528879f.mock.pstmn.io/user \
-H "x-mock-match-request-body: true" | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   243  100   243    0     0    534      0 --:--:-- --:--:-- --:--:--   534
{
  "error": {
    "name": "mockRequestNotFoundError",
    "message": "Double check your method and the request path and try again. Learn more here: https://learning.postman.com/docs/design-apis/mock-apis/matching-algorithm/",
    "header": "No matching requests"
  }
}

example에서 정의한 요청 body와 실제 요청 body가 일치하지 않으므로 API를 찾지 못하여 에러가 발생한다.

이제 x-mock-match-request-body 헤더와 함께 요청 body를 함께 전송해 보자. 이때 주의해야 할 점은 요청/Example 모두 Content-Type 헤더가 동일해야 한다. (ex. application/json) 또한 문자열이 정말 일치해야 한다. (공백이나 순서가 다르면 실패한다)

 ~/ curl -X POST https://d4879412-6baf-4610-8fe5-08d28528879f.mock.pstmn.io/user \
-H "Content-Type: application/json" \
-H "x-mock-match-request-body: true" \
-d '{
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "010-1234-5678"
}' | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   175    0    94  100    81    210    181 --:--:-- --:--:-- --:--:--   391
{
  "id": 100,
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "010-1234-5678"
}

Mock Server Example 필터링 헤더

Postman Mock Server는 Example을 선택할 때 다음과 같은 순서로 필터링한다.

경로(path) -> HTTP Method -> 쿼리 파라미터 -> 헤더/바디

이때 마지막 헤더/바디 단계에서 Example을 필터링할 수 있도록 지원하는 헤더가 있는데 이는 다음과 같다.

헤더 이름	설명
x-mock-response-code	특정 HTTP 상태코드를 응답하는 Example만 필터링
x-mock-response-name	Example 이름을 지정
x-mock-response-id	Example의 UID로 직접 지정
x-mock-match-request-body	요청 body와 Example 요청 body가 일치하는 Example 필터링

Example의 ID를 확인하는 방법은 Example의 info 메뉴를 통해서 확인 가능하다.

예를 들어 GET메서드에 Path는 /user/list로 정의한 get user list라는 request가 있다고 가정했을 때(get user list는 list를 응답하도록 example을 정의) get user list Example을 호출하는 요청에서 x-mock-response-id를 get user example의 UID로 지정하면 get user example의 상태코드와 body payload를 응답한다.

 ~/ curl https://d4879412-6baf-4610-8fe5-08d28528879f.mock.pstmn.io/user/list \
-H "x-mock-response-id: 12345241-64d4a768-6885-49a8-8251-9113d7036d9e"
{
  "id": list,
  "name": "아무개",
  "email": "noname@example.com",
  "phone": "010-1234-5678"
}

끝.

참고링크

https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/

https://learning.postman.com/docs/design-apis/mock-apis/mock-server-calls/

https://learning.postman.com/docs/design-apis/mock-apis/tutorials/mock-with-examples/

https://learning.postman.com/docs/design-apis/mock-apis/tutorials/mock-with-api/

저작자표시 비영리 변경금지 (새창열림)

'ETC' 카테고리의 다른 글

티스토리 블로그에 구글 애널리틱스 연동 실패, 이렇게 해결했습니다 (0)	2025.10.22
Multipass 사용법: 간편하게 가상 머신 관리하기 (0)	2024.07.02
mongodb - $push와 $addToSet의 차이점 (0)	2024.02.18
맥 m1, m2 에 jmeter 사용하기 (0)	2023.12.02
맥 환경에서 iTerm2 개발 환경 셋팅하기 (0)	2023.12.01