DEV Community

Cover image for Apidog를 활용한 공유형 클라우드 목 서버 구축 가이드
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Apidog를 활용한 공유형 클라우드 목 서버 구축 가이드

프런트엔드 팀이 작업에 막혔습니다. 디자인은 승인됐고 화면도 절반쯤 완성됐지만, 호출할 실제 API가 아직 없습니다. 백엔드 배포까지 한 스프린트가 남은 상황에서 로컬 목(mock)은 개인 노트북이 켜져 있을 때만 동작합니다. 다른 시간대의 팀원이 같은 엔드포인트를 사용해야 한다면, 항상 접근 가능한 공유 목이 필요합니다.

지금 Apidog 사용해 보기

Apidog의 Cloud Mock을 사용하면 mock.apidog.com에서 호스팅되는 공개 URL을 만들 수 있습니다. 프런트엔드, QA, 파트너 개발자는 백엔드 코드가 배포되기 전에도 동일한 API 계약을 기준으로 작업할 수 있습니다.

API 목의 용도와 시점이 궁금하다면 API 목이란 무엇이며 언제 사용해야 하는지를 참고하세요. 공개 목 URL이 HTTP 요청과 응답을 처리하는 방식은 MDN의 HTTP 요청/응답 모델에서 복습할 수 있습니다.

클라우드 목이란 무엇이며 로컬 목이 부족한 이유

Apidog는 API 설계에 따라 목 엔드포인트를 생성합니다. 로컬 목은 Apidog 인스턴스에서 실행되므로 컴퓨터가 꺼지거나 절전 상태가 되면 응답하지 않습니다. 개인 디버깅에는 충분하지만, 팀이 같은 URL에 의존하기 시작하면 문제가 됩니다.

Cloud Mock은 특정 개발자 머신과 독립적으로 동작하는 호스팅 목 엔드포인트입니다. 팀원의 노트북이 꺼져 있어도 URL은 계속 요청을 처리합니다.

실무에서는 다음 순서로 사용하면 됩니다.

  1. API 계약과 응답 스키마를 설계합니다.
  2. Cloud Mock을 활성화합니다.
  3. 생성된 URL을 프런트엔드, QA, 파트너에게 공유합니다.
  4. 실제 백엔드가 준비되면 같은 계약을 기준으로 전환 및 검증합니다.

글로벌 팀에서 환경과 목 서버를 공유해야 한다면 글로벌 팀과 목 서버 및 환경을 공유하는 방법을 참고하세요.

Cloud Mock 활성화 및 공개 URL 얻기

예제로 고객 목록을 반환하는 GET /users 엔드포인트를 사용하겠습니다.

1. Cloud Mock 켜기

Apidog 프로젝트에서 다음 경로로 이동합니다.

프로젝트 설정(Project Settings) > 기능 설정(Feature Settings) > 목 설정(Mock Settings)

여기서 Cloud Mock을 활성화합니다.

이 설정은 프로젝트당 한 번만 하면 됩니다. 활성화 후 프로젝트의 엔드포인트는 로컬 목 URL과 함께 클라우드 목 URL을 사용할 수 있습니다.

Cloud Mock 설정 화면

2. 클라우드 목 URL 복사

GET /users를 열고 목(Mock) 탭으로 이동합니다. 표시된 Cloud Mock URL을 복사합니다.

https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi
Enter fullscreen mode Exit fullscreen mode

URL은 일반적으로 다음 구조를 따릅니다.

https://mock.apidog.com/m1/<projectId>-<num>-<env>/<path>
Enter fullscreen mode Exit fullscreen mode

직접 URL을 조합하지 말고 Apidog가 생성한 URL을 그대로 사용하세요. 생성된 URL이 현재 프로젝트와 환경에 대한 기준입니다.

3. Apidog에서 목 응답 테스트

URL을 공유하기 전에 목(Mock) 탭에서 테스트 요청을 실행합니다. 응답이 스키마와 맞는지, 프런트엔드가 기대하는 필드가 포함됐는지 확인하세요.

GET /users는 다음과 같이 응답할 수 있습니다.

[
  {
    "id": 1,
    "name": "Amelia Turner",
    "email": "amelia.turner@example.com",
    "city": "Portland"
  },
  {
    "id": 2,
    "name": "Marcus Bell",
    "email": "marcus.bell@example.com",
    "city": "Austin"
  }
]
Enter fullscreen mode Exit fullscreen mode

Apidog는 스키마의 필드 이름과 타입을 바탕으로 목 데이터를 생성합니다. 따라서 프런트엔드는 단순한 "string" 대신 실제 UI 검증에 사용할 수 있는 형태의 데이터를 받습니다.

4. 브라우저 또는 curl로 확인

GET 요청은 브라우저 주소창에서 직접 열어 JSON 응답을 확인할 수 있습니다.

터미널에서는 다음처럼 호출합니다.

curl "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
Enter fullscreen mode Exit fullscreen mode

이제 백엔드 배포 전에도 프런트엔드는 공유 URL을 대상으로 개발할 수 있습니다.

토큰 인증으로 목 보호하기

공개 URL은 편리하지만, 출시 전 기능이나 파트너 통합 정보를 포함한다면 접근을 제한해야 할 수 있습니다.

다음 경로에서 접근 권한을 토큰 인증(Token Authentication) 으로 설정합니다.

프로젝트 설정(Project Settings) > 기능 설정(Feature Settings) > 목 설정(Mock Settings)

활성화하면 모든 요청에 유효한 apidogToken이 필요합니다. 토큰은 세 가지 방식으로 전달할 수 있습니다.

쿼리 문자열로 전달 

curl "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
Enter fullscreen mode Exit fullscreen mode

요청 헤더로 전달

URL과 서버 로그에 토큰을 남기고 싶지 않다면 헤더를 사용합니다.

curl "https://mock.apidog.com/m1/2689726-0-default/users" \
  -H "apidogToken: GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
Enter fullscreen mode Exit fullscreen mode

폼 본문으로 전달

form-data 또는 x-www-form-urlencoded 요청에서는 apidogToken이라는 본문 매개변수를 사용할 수 있습니다.

프런트엔드에서는 보통 헤더 방식이 가장 관리하기 쉽습니다.

const res = await fetch(
  "https://mock.apidog.com/m1/2689726-0-default/users",
  {
    headers: {
      apidogToken: "GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
    }
  }
);

const users = await res.json();
Enter fullscreen mode Exit fullscreen mode

이미 일반 URL을 공유한 뒤 토큰 인증을 켜면 기존 호출은 실패합니다. QA, 프런트엔드, 파트너에게 전환 시점과 토큰 전달 방식을 미리 공유하세요.

로케일로 실제와 같은 지역별 데이터 생성하기

"name": "string"만 반환하는 목은 UI 검증에 도움이 되지 않습니다. 실제 이름, 주소, 전화번호와 비슷한 데이터를 사용해야 텍스트 길이, 줄바꿈, 주소 형식, 비라틴 문자 처리 문제를 조기에 찾을 수 있습니다.

Apidog는 Faker.js 기반의 데이터 생성을 지원하며, 로케일 설정으로 지역에 맞는 데이터를 생성할 수 있습니다.

기본 로케일 설정

기본적으로 Faker는 프로젝트 언어 설정을 따릅니다.

프로젝트 설정(Project Settings) > 기본 설정(Basic Settings)

여기서 선택한 언어가 생성되는 목 데이터의 기본 로케일이 됩니다. 예를 들어 프로젝트 언어를 프랑스어로 설정하면 이름과 주소도 프랑스어 스타일로 생성됩니다.

프로젝트 전체 로케일 재정의

프로젝트 언어와 다른 로케일의 목 데이터가 필요하다면 다음 경로에서 Faker 로케일을 지정합니다.

프로젝트 설정(Project Settings) > 기능 설정(Feature Settings) > 목 설정(Mock Settings)

이 값은 기본 설정의 언어보다 우선합니다. 국제화 테스트에서는 일본, 독일 등 대상 시장의 로케일을 지정해 주소 형식과 문자 폭을 검증할 수 있습니다.

스키마를 기반으로 데이터를 생성하는 방식은 Apidog 스마트 목과 스키마를 읽는 방법에서 자세히 확인할 수 있습니다.

필드별 로케일 재정의

특정 필드에만 다른 로케일을 적용할 수도 있습니다. 예를 들어 전체 응답은 기본 로케일을 따르되, 이름 필드만 일본어 데이터로 만들 수 있습니다.

{{$person.fullName(locale='ja')}}
Enter fullscreen mode Exit fullscreen mode

이 표현식은 해당 필드에 田中 太郎 같은 일본어 이름을 생성합니다.

로케일 우선순위는 다음과 같습니다.

  1. 필드 수준 locale
  2. 프로젝트 수준 Faker 로케일
  3. 기본 설정(Basic Settings)의 프로젝트 언어

지원되는 로케일 코드는 사용 전에 Apidog 목 문서와 Faker.js 로케일 문서에서 확인하세요.

시간대도 맞추기

시간 관련 필드도 같은 방식으로 제어할 수 있습니다.

  • 프로젝트 기본 시간대: 프로젝트 설정 > 기능 설정 > 목 설정
  • 필드별 시간대: 목 표현식의 timeZone 매개변수

createdAt 같은 필드가 있다면 테스트 대상 지역의 시간대를 사용하세요. 서버 기본 시간대로 생성된 값 때문에 날짜가 바뀌거나 UI 표기가 달라지는 문제를 줄일 수 있습니다.

더 다양한 활용 사례는 실용적인 API 목킹 사용 사례에서 확인할 수 있습니다.

클라우드 목과 자체 호스팅 목 비교

Cloud Mock은 설정 부담이 적은 호스팅 옵션입니다. 반면 데이터 상주 규정이나 사내 네트워크 정책 때문에 외부 클라우드를 사용할 수 없다면 자체 인프라에서 목 서비스를 운영해야 할 수 있습니다.

선택지 적합한 경우 고려 사항
Cloud Mock 빠른 공유, 팀 협업, 유지보수 최소화 호스팅 서비스 사용
자체 호스팅 목 데이터 상주 규정, 내부망 요구사항 운영과 유지보수 필요

자체 호스팅이 필요한 경우 Apidog 목 서버 자체 호스팅 가이드를 참고하세요. 도구 선택을 비교 중이라면 온라인 API 목킹 도구 비교도 도움이 됩니다.

Cloud Mock과 로케일 기능의 플랜별 제공 여부는 계정 상태에 따라 직접 확인하는 것이 좋습니다. Apidog 다운로드 후 실제 프로젝트에서 워크플로를 테스트해 보세요.

Apidog CLI로 계약 검증 자동화하기

Apidog의 목 응답은 GUI와 호스팅 엔진에서 제공됩니다. Apidog CLI는 목 서버를 시작하거나 서비스하지 않습니다.

대신 CLI는 실제 백엔드가 준비된 후, 목이 기준으로 삼았던 API 계약을 자동으로 검증하는 데 사용할 수 있습니다.

워크플로는 다음과 같습니다.

  1. API 엔드포인트와 스키마를 Apidog 프로젝트에서 관리합니다.
  2. Cloud Mock이 해당 스키마를 기반으로 프런트엔드용 데이터를 제공합니다.
  3. 백엔드 배포 후 저장된 테스트 시나리오를 CLI로 실행합니다.
  4. 같은 계약을 기준으로 실제 백엔드 응답을 검증합니다.

예를 들어 다음 명령으로 시나리오를 실행합니다.

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Apidog에서 시나리오를 열고 자동 생성된 명령을 복사하면 -t 시나리오 ID와 -e 환경 ID를 직접 조립할 필요가 없습니다.

CI/CD 연결 방법은 CI/CD 파이프라인에서 Apidog 실행 가이드를 참고하세요.

자주 묻는 질문

Apidog를 닫아도 Cloud Mock URL이 계속 작동하나요?

네. 로컬 목과 달리 Cloud Mock은 Apidog 인프라에서 호스팅되므로 개발자 컴퓨터가 꺼져 있어도 요청을 처리합니다.

브라우저에서 Cloud Mock URL을 직접 열 수 있나요?

GET 요청은 가능합니다. 전체 URL을 주소창에 붙여넣으면 JSON 응답을 확인할 수 있습니다.

다만 토큰을 URL 기록에 남기고 싶지 않다면 curl, API 클라이언트, 프런트엔드 코드에서 헤더 방식으로 전달하세요.

토큰 없이 요청하면 어떻게 되나요?

접근 권한이 토큰 인증으로 설정되어 있다면 유효한 apidogToken이 없는 요청은 거부됩니다. 토큰은 쿼리 문자열, 요청 헤더, 폼 본문 중 하나로 전달해야 합니다.

특정 국가에 맞는 목 데이터를 생성하려면 어떻게 하나요?

다음 세 가지 수준에서 설정할 수 있습니다.

  1. 기본 설정(Basic Settings): 프로젝트 기본 언어 설정
  2. 목 설정(Mock Settings): 프로젝트 전체 Faker 로케일 재정의
  3. 목 표현식: 특정 필드에 locale 지정

예시는 다음과 같습니다.

{{$person.fullName(locale='ja')}}
Enter fullscreen mode Exit fullscreen mode

필드 수준 설정이 프로젝트 수준 설정보다 우선합니다. 자세한 생성 방식은 스마트 목 가이드를 참고하세요.

Cloud Mock과 헤드리스 목 도구 중 무엇을 선택해야 하나요?

API 설계와 연결된 호스팅 목 URL을 빠르게 공유하려면 Cloud Mock이 적합합니다. GUI 없이 자동화 빌드에 목을 포함해야 한다면 헤드리스 API 목 도구 조사를 확인하세요.

대부분의 도구는 OpenAPI Initiative 사양을 기반으로 동작하므로, 어떤 도구를 선택하든 API 명세를 정확히 유지하는 것이 중요합니다.

마무리

로컬에서만 동작하는 목은 개인 개발 환경에는 충분하지만 팀 협업에는 부족합니다. Cloud Mock을 사용하면 API 계약을 공유 가능한 mock.apidog.com URL로 제공할 수 있습니다.

핵심 절차는 간단합니다.

  1. 엔드포인트와 스키마를 설계합니다.
  2. Cloud Mock을 활성화합니다.
  3. 생성된 URL을 공유합니다.
  4. 필요하면 토큰 인증과 로케일을 설정합니다.
  5. 실제 백엔드 배포 후 CLI 시나리오로 같은 계약을 검증합니다.

Apidog를 다운로드하여 첫 번째 공유 가능한 Cloud Mock을 설정해 보세요.

Top comments (0)