DEV Community

Cover image for Apidog에서 HAR 파일 가져오기: 캡처 트래픽으로 API 엔드포인트 만들기
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Apidog에서 HAR 파일 가져오기: 캡처 트래픽으로 API 엔드포인트 만들기

브라우저에서 앱이 보내는 요청을 본 적이 있을 것입니다. 네트워크 탭에는 URL, 헤더, JSON 본문, 응답이 그대로 남습니다. 이를 수동으로 다시 입력하는 대신, 캡처한 호출을 저장하고 문서화된 엔드포인트로 가져와 모의 응답과 테스트에 활용할 수 있습니다.

지금 Apidog 사용해 보기

HAR 파일은 “눈에 보이는 트래픽”과 “재사용 가능한 엔드포인트” 사이를 연결합니다. 브라우저가 이미 기록한 요청과 응답을 HAR로 내보낸 뒤 Apidog로 가져오면, 캡처된 호출이 프로젝트의 API 엔드포인트가 됩니다.

이 글에서는 다음 과정을 다룹니다.

  1. Chrome DevTools에서 HAR 캡처하기
  2. Apidog로 HAR 가져오기
  3. 생성된 엔드포인트 정리하기
  4. CLI로 가져오기와 테스트 자동화하기

캡처 워크플로를 더 폭넓게 살펴보고 싶다면 Apidog와 함께하는 패킷 캡처 도구를 참고하세요.

Apidog를 무료로 다운로드한 뒤 같은 화면에서 따라 해 볼 수 있습니다.

HAR 파일이란 무엇이며, 왜 보관해야 할까요?

HAR은 HTTP Archive의 약자입니다. Apidog 문서에서 .har 파일은 웹 브라우저와 사이트 간 상호 작용을 기록하는 JSON 형식 파일로 설명됩니다. 요청, 응답, 헤더, 그리고 브라우저와 서버 사이에서 전송된 데이터를 포함합니다.

즉, HAR은 브라우징 세션의 기록입니다. 다음과 같은 정보가 들어 있습니다.

  • 모든 GET, POST 요청
  • 요청 URL과 쿼리 파라미터
  • 요청 헤더와 본문
  • 응답 상태 코드와 본문
  • 요청 타이밍 정보

HAR을 엔드포인트로 전환하면 다음을 바로 확보할 수 있습니다.

  • 실제 요청 형태: 앱이 실제로 보낸 URL, 헤더, 파라미터, 본문
  • 실제 응답: 서버가 반환한 상태 코드와 페이로드
  • 문서화 시작점: 문서가 없던 내부 API를 정리할 수 있는 엔드포인트 목록

이 방식은 특히 다음 상황에서 유용합니다.

  • OpenAPI 스펙 없이 운영 중인 서비스를 인수한 경우
  • 서드파티 위젯이 백엔드와 통신하는 방식을 분석해야 하는 경우
  • 특정 버그를 재현한 실제 API 호출을 저장해야 하는 경우

1단계: 브라우저 DevTools에서 HAR 캡처하기

HAR 캡처는 Apidog가 아니라 브라우저 DevTools에서 수행합니다. Chrome과 Edge는 같은 DevTools 흐름을 사용합니다.

예를 들어 주문 내역 페이지에서 발생하는 API 트래픽을 캡처해 보겠습니다.

  1. 기록할 페이지를 엽니다. 인증이 필요한 API라면 먼저 로그인합니다.
  2. 개발자 도구를 엽니다.
    • Windows/Linux: F12 또는 Ctrl+Shift+I
    • macOS: Cmd+Opt+I
  3. Network 탭으로 이동합니다.
  4. 페이지를 새로고침하거나, 캡처하려는 동작을 수행합니다.
    • 예: 주문 내역 페이지를 열면 /api/orders, /api/orders/{id} 등의 요청이 표시됩니다.
  5. 요청 목록에서 아무 행이나 마우스 오른쪽 버튼으로 클릭한 뒤 Save all as HAR with content를 선택합니다.
  6. 예를 들어 order-history.har라는 이름으로 파일을 저장합니다.

메뉴가 보이지 않거나 이름이 다르게 표시된다면 Chrome DevTools Network 문서를 참고하세요.

반드시 with content로 내보내세요

Save all as HAR with content의 with content는 중요합니다.

이 옵션을 선택해야 요청 메타데이터뿐 아니라 응답 본문도 HAR에 포함됩니다. 응답 본문이 없으면 Apidog로 가져온 엔드포인트에는 요청 정보만 있고, 모의 응답이나 테스트 검증에 사용할 응답 예시가 없습니다.

내보낸 후 간단히 확인하려면 .har 파일을 텍스트 편집기로 열어 보세요. 다음과 비슷한 구조를 확인할 수 있습니다.

{
  "log": {
    "entries": [
      {
        "request": {},
        "response": {}
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Apidog는 이 entries 배열의 request와 response 정보를 읽어 엔드포인트를 생성합니다.

페이지 로드에는 API 호출뿐 아니라 이미지, CSS, JavaScript 파일도 포함됩니다. 브라우저에서 미리 완벽하게 필터링할 필요는 없습니다. Apidog 가져오기 옵션에서 정적 리소스를 제외할 수 있습니다.

2단계: HAR을 Apidog로 가져오기

HAR 파일을 저장했다면 Apidog 프로젝트에서 가져오기를 시작합니다.

  1. 프로젝트를 엽니다.
  2. Settings > Import Data > Manual로 이동합니다.
  3. 형식으로 HAR를 선택합니다.
  4. order-history.har 같은 .har 파일을 업로드합니다.

가져오기를 실행하기 전, 다음 세 가지 옵션을 확인하세요. 이 설정이 생성되는 엔드포인트 목록의 품질을 크게 좌우합니다.

옵션 1: BaseURL 처리 방식

캡처된 요청에는 보통 전체 URL이 들어 있습니다.

https://api.shop.example.com/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

BaseURL 처리 방식에는 두 가지가 있습니다.

  • Hardcode: 전체 BaseURL을 엔드포인트 URL에 유지합니다.
  • Remove (권장): BaseURL을 제거하고 경로만 남깁니다.

Remove를 선택하면 다음처럼 가져옵니다.

/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

대부분의 경우 Remove를 선택하는 것이 좋습니다. BaseURL을 환경 변수로 분리하면 같은 엔드포인트를 여러 환경에서 재사용할 수 있기 때문입니다.

# Production
https://api.shop.example.com

# Staging
https://staging-api.shop.example.com

# Local
http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

이렇게 구성하면 엔드포인트 경로를 수정하지 않고 환경만 바꿔 테스트할 수 있습니다. BaseURL은 환경 변수를 통해 전역적으로 관리할 수 있습니다.

옵션 2: 정적 리소스 제외

Static Resource 옵션은 정적 파일을 엔드포인트 목록에서 제외합니다.

이 옵션을 Exclude로 설정하면 다음 같은 요청을 건너뜁니다.

/logo.png
/app.css
/main.js
/favicon.ico
Enter fullscreen mode Exit fullscreen mode

대신 실제 API 트래픽에 집중할 수 있습니다.

/api/orders
/api/orders/123
/api/users/me
Enter fullscreen mode Exit fullscreen mode

거의 모든 HAR 가져오기에서는 Static Resource: Exclude를 권장합니다. 페이지 하나만 열어도 수십 개의 이미지, 스타일시트, 스크립트 요청이 생성될 수 있기 때문입니다.

옵션 3: 엔드포인트별 테스트 케이스 생성

Endpoint Case Generation을 켜면 Apidog는 가져온 각 엔드포인트에 기본 테스트 케이스를 생성합니다.

테스트까지 바로 진행할 계획이라면 이 옵션을 켜세요. 캡처 시점의 요청 값이 채워진 상태로 저장되므로, 엔드포인트별로 처음부터 테스트 요청을 만들 필요가 없습니다.

문서화만 먼저 진행하려면 이 옵션을 끄고 나중에 테스트 케이스를 추가해도 됩니다.

가져온 엔드포인트 예시

가져오기가 완료되면 캡처된 요청이 엔드포인트 트리에 표시됩니다.

GET /v1/orders/123
Host: api.shop.example.com
Authorization: Bearer <token-from-capture>
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

HAR에 응답 본문이 포함되어 있었다면 다음 같은 데이터도 함께 저장됩니다.

{
  "id": 123,
  "status": "shipped",
  "total": 48.5,
  "currency": "USD",
  "items": [
    {
      "sku": "TSHIRT-BLK-M",
      "qty": 2,
      "price": 19.25
    }
  ],
  "createdAt": "2026-07-14T09:31:00Z"
}
Enter fullscreen mode Exit fullscreen mode

이 응답은 실제 서버가 반환한 데이터이므로 모의 응답이나 테스트 검증의 출발점으로 사용할 수 있습니다.

3단계: 생성된 엔드포인트 정리하기

HAR 가져오기는 빠른 시작점입니다. 하지만 캡처된 트래픽은 그대로 문서가 되기에는 정리가 필요합니다.

불필요한 엔드포인트 삭제

정적 리소스를 제외했더라도 다음 같은 요청이 남을 수 있습니다.

  • 분석 이벤트
  • 헬스 체크
  • 서드파티 추적 요청
  • 현재 문서화 범위와 무관한 호출

사용하지 않을 엔드포인트는 삭제해 API 트리가 실제 서비스 구조를 반영하게 하세요.

이름 변경 및 그룹화

캡처된 엔드포인트는 보통 경로 중심으로 이름이 만들어집니다. 기능적으로는 충분하지만, 협업과 문서화에는 더 명확한 이름이 좋습니다.

예를 들어 다음 엔드포인트를:

GET /v1/orders/123
Enter fullscreen mode Exit fullscreen mode

다음처럼 정리할 수 있습니다.

주문
└── ID로 주문 조회
    └── GET /v1/orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

도메인 또는 기능별 폴더로 그룹화하면 API 탐색이 훨씬 쉬워집니다.

리터럴 경로를 경로 파라미터로 변경

HAR은 실제 호출을 캡처하므로 URL의 값도 그대로 들어옵니다.

/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

여기서 123이 특정 주문 ID라면 다음처럼 변경하세요.

/v1/orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

이제 한 번 캡처한 요청이 특정 주문 하나가 아니라 모든 주문 ID에 재사용 가능한 엔드포인트가 됩니다.

민감 정보 제거

HAR에는 실제 세션 중 사용된 인증 정보가 포함될 수 있습니다.

Authorization: Bearer eyJhbGciOi...
Cookie: session_id=...
Enter fullscreen mode Exit fullscreen mode

프로젝트를 공유하거나 저장소에 커밋하기 전에 다음을 수행하세요.

  1. 실제 토큰과 쿠키를 삭제합니다.
  2. 인증 값은 환경 변수로 이동합니다.
  3. 예시 요청과 예시 응답에 민감한 데이터가 없는지 확인합니다.
  4. HAR 파일 자체도 비밀 정보로 취급합니다.

Stripe 키 관리 문서도 라이브 키가 공유 아티팩트에 포함되지 않도록 주의할 것을 강조합니다. HAR 역시 실제 자격 증명이 포함될 수 있는 공유 아티팩트입니다.

응답 본문이 비어 있을 때

가져온 요청에 응답 데이터가 없다면 HAR을 with content 없이 내보냈을 수 있습니다.

다음 순서로 다시 진행하세요.

  1. DevTools의 Network 탭을 엽니다.
  2. 필요한 동작을 다시 수행합니다.
  3. Save all as HAR with content를 선택합니다.
  4. 새 HAR 파일을 Apidog로 다시 가져옵니다.

정리된 엔드포인트는 Apidog의 다른 API와 동일하게 사용할 수 있습니다. 문서화, 모의 응답 생성, 테스트 시나리오 구성까지 이어갈 수 있습니다.

다음 단계는 Apidog에서 테스트 시나리오 작성하기를 참고하세요. 타입이 지정된 클라이언트 코드가 필요하다면 Apidog로 클라이언트 코드 생성하는 방법을 확인할 수 있습니다.

변형과 한계

자동 트래픽 레코더는 현재 지원되지 않습니다

Apidog가 프록시처럼 백그라운드에서 모든 트래픽을 실시간 기록할 것으로 기대할 수 있습니다. 하지만 현재 지원되는 흐름은 다음과 같습니다.

  1. 브라우저 DevTools에서 트래픽 캡처
  2. HAR 파일 내보내기
  3. Apidog로 HAR 가져오기
  4. 엔드포인트 정리 및 테스트 시나리오 생성

즉, 실시간 자동 레코더가 아니라 HAR 기반의 수동 캡처 및 가져오기 방식입니다.

Apidog 브라우저 확장 프로그램은 HAR 캡처 도구가 아닙니다

Apidog 브라우저 확장 프로그램은 브라우저에서 API를 테스트하고 디버깅하는 데 사용할 수 있습니다. 하지만 이 확장 프로그램은 HAR 트래픽을 자동 캡처하는 기능과는 다릅니다.

HAR 캡처는 브라우저 DevTools에서 수행해야 합니다.

또한 브라우저 확장 프로그램은 브라우저 제약을 받습니다. 예를 들어 다음과 같은 제한이 있을 수 있습니다.

  • Cookie, Host, Origin, Content-Length 등 특정 헤더 제한
  • GET, HEAD 요청에 본문을 전송하지 못하는 제한
  • 로컬 머신 또는 사설 네트워크 리소스 접근 제한

완전한 헤더 제어가 필요한 디버깅은 데스크톱 클라이언트를 사용하고, 트래픽 캡처는 DevTools와 HAR 내보내기를 사용하세요.

다른 형식도 가져올 수 있습니다

HAR은 Settings > Import Data > Manual에서 지원하는 여러 형식 중 하나입니다.

이미 OpenAPI 또는 Swagger 파일이 있다면, HAR보다 더 구조화된 결과를 얻을 수 있습니다. 스펙에는 엔드포인트, 파라미터, 응답 스키마가 의도적으로 정의되어 있기 때문입니다.

실제 스펙이 없고 캡처된 트래픽이 가장 신뢰할 수 있는 기록일 때 HAR 가져오기를 사용하세요.

Apidog CLI로 워크플로 자동화하기

HAR 가져오기는 GUI에서만 할 필요가 없습니다. Apidog CLI의 import 명령으로 HAR 파일을 프로젝트에 직접 가져올 수 있습니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

# 캡처한 HAR을 프로젝트의 엔드포인트로 가져오기
apidog import --project <PROJECT_ID> --format har --file ./capture.har
Enter fullscreen mode Exit fullscreen mode

이 방식은 다음과 같은 경우에 유용합니다.

  • 서버에서 캡처한 HAR을 처리할 때
  • 스크립트나 파이프라인으로 가져오기를 자동화할 때
  • AI 코딩 에이전트가 캡처 파일을 엔드포인트로 전환해야 할 때

--format 플래그는 har 외에도 openapi, postman, wsdl, insomnia 등을 지원합니다.

가져온 엔드포인트로 테스트 시나리오를 만들었다면 CI에서 실행할 수 있습니다.

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> -e <ENV_ID> -r cli
Enter fullscreen mode Exit fullscreen mode

옵션 의미는 다음과 같습니다.

옵션 설명
-t 저장된 테스트 시나리오 ID
-e 환경 ID
-r cli 콘솔 출력용 CLI 리포터

테스트 시나리오는 Apidog에서 테스트 시나리오 작성하기를 따라 만들고, CI 연결은 Apidog CLI CI/CD 가이드를 참고하세요.

자주 묻는 질문

어떤 브라우저에서 HAR을 내보낼 수 있나요?

DevTools를 사용하는 Chromium 기반 브라우저라면 같은 방식으로 사용할 수 있습니다. Chrome과 Edge에서는 Network 탭에서 Save all as HAR with content 메뉴를 찾으면 됩니다.

다른 브라우저도 HAR 내보내기를 지원할 수 있지만, 메뉴 이름은 다를 수 있습니다.

가져온 엔드포인트가 너무 많습니다. 무엇이 문제인가요?

대부분 정적 리소스를 포함했기 때문입니다.

가져오기에서 Static Resource를 Exclude로 설정한 뒤 다시 가져오세요. 이미지, CSS, JavaScript 파일이 제외되고 실제 API 호출 중심의 목록이 남습니다.

그래도 불필요한 분석 요청이나 서드파티 호출이 남으면 수동으로 삭제하세요.

BaseURL은 Hardcode와 Remove 중 무엇을 선택해야 하나요?

대부분의 경우 Remove (권장)를 선택하세요.

이 설정은 BaseURL을 엔드포인트 경로에서 분리하고 환경 변수로 관리할 수 있게 합니다. 따라서 프로덕션, 스테이징, 로컬 환경을 전환할 때 엔드포인트를 수정할 필요가 없습니다.

전체 URL을 모든 경로에 고정해야 하는 특별한 이유가 있을 때만 Hardcode를 선택하세요.

HAR에 인증 토큰도 포함되나요?

네. HAR은 세션 중 실제로 전송된 헤더를 기록하므로 베어러 토큰, 쿠키, 세션 ID가 포함될 수 있습니다.

HAR 파일을 비밀 정보처럼 취급하세요.

  • 공개 이슈에 첨부하지 않기
  • 저장소에 커밋하지 않기
  • 공유 전 토큰과 쿠키 삭제하기
  • 인증 값은 환경 변수로 관리하기

GUI 없이 CLI로 HAR을 가져올 수 있나요?

네. 다음 명령을 사용하면 됩니다.

apidog import --project <PROJECT_ID> --format har --file ./capture.har
Enter fullscreen mode Exit fullscreen mode

서버나 CI 작업에서 HAR을 처리할 때 유용합니다.

다만 GUI는 BaseURL 처리, 정적 리소스 필터링처럼 가져오기 결과를 대화형으로 조정할 수 있습니다. 자동화에는 CLI를, 일회성 캡처를 검토하면서 가져올 때는 GUI를 사용하세요.

마무리

HAR 파일은 브라우저에서 보이는 실제 트래픽을 재사용 가능한 API 엔드포인트로 전환하는 방법입니다.

핵심 흐름은 다음과 같습니다.

  1. DevTools에서 Save all as HAR with content로 캡처합니다.
  2. Apidog의 Settings > Import Data > Manual에서 HAR을 가져옵니다.
  3. BaseURL은 Remove, 정적 리소스는 Exclude를 선택합니다.
  4. 생성된 엔드포인트의 이름을 변경하고 폴더로 그룹화합니다.
  5. 리터럴 ID를 경로 파라미터로 바꿉니다.
  6. 토큰, 쿠키 등 민감 정보를 제거하고 환경 변수로 옮깁니다.
  7. 모의 응답, 문서, 테스트 시나리오로 확장합니다.

다음 캡처를 실제 엔드포인트로 전환할 준비가 되었다면 Apidog를 다운로드해 무료로 시작해 보세요.

Top comments (0)