브라우저에서 앱이 요청하는 것을 보셨을 겁니다. 작동하죠. 데이터는 네트워크 탭에 고스란히 있습니다. 이제 URL, 헤더, JSON 본문을 수동으로 다시 입력할 필요 없이, 저장하고, 모의 응답을 만들고, 테스트할 수 있는 문서화된 엔드포인트로 그 동일한 호출을 사용하고 싶을 것입니다.
"눈에 보이는 트래픽"과 "재사용 가능한 엔드포인트" 사이의 간극을 HAR 파일이 메워줍니다. 브라우저는 이미 모든 요청과 응답을 기록하고 있습니다. 그 기록을 내보내기하여 Apidog에 전달하면, 캡처된 각 호출이 프로젝트 내에서 실제 엔드포인트가 됩니다. 이 가이드는 Chrome DevTools에서 HAR을 캡처하고, 올바른 옵션으로 가져오고, 생성된 엔드포인트를 정리하여 목록이 유용하게 유지되도록 전체 과정을 안내합니다. 캡처 워크플로에 대한 더 넓은 시야를 원하시면, Apidog와 함께하는 패킷 캡처 도구 가이드를 참조하세요.
Apidog를 무료로 다운로드하여 같은 화면에서 따라 해 볼 수 있습니다.
HAR 파일이란 무엇이며 캡처된 트래픽을 보관할 가치가 있는 이유
HAR은 HTTP Archive의 약자입니다. Apidog 문서에 따르면, .har 파일은 “웹 브라우저와 사이트 간의 상호 작용을 기록하는 데 사용되는 JSON 형식의 파일입니다. 웹 요청, 응답, 헤더 및 브라우저와 서버 간에 전송된 기타 데이터를 기록합니다.”
쉽게 말해, HAR 파일은 브라우징 세션의 전체 기록입니다. 모든 GET, 모든 POST, 요청 헤더, 응답 본문, 타이밍 정보가 담겨 있습니다. JSON 형식이기 때문에 전송하기 용이합니다. 이메일로 보내거나, 버그 보고서에 첨부하거나, 이를 읽을 수 있는 도구에 입력할 수 있습니다.
바로 이 마지막 부분이 여기서 중요한 이유입니다. 캡처된 세션은 API가 실제 환경에서 어떻게 동작하는지에 대한 기록이며, 스펙이 명시하는 방식과는 다릅니다. 이 기록을 엔드포인트로 전환하면 몇 가지를 무료로 얻을 수 있습니다:
- 실제 요청 형태. 앱이 보낸 정확한 URL, 쿼리 파라미터, 헤더, 본문 (추측이 아님).
- 실제 응답. 서버가 반환한 상태 코드와 페이로드로, 모의 응답 또는 테스트 검증으로 사용할 수 있습니다.
- 문서화의 시작점. 문서화되지 않은 내부 API가 주석을 달 수 있는 명명된 엔드포인트 세트가 됩니다.
이는 OpenAPI 스펙이 없는 서비스를 물려받았을 때, 타사 위젯이 백엔드와 통신하는 방식을 역설계할 때, 또는 특정 버그를 유발한 정확한 호출로 버그를 재현하고 싶을 때 유용합니다.
1단계: 브라우저 DevTools에서 HAR 캡처하기
캡처는 Apidog가 아닌 브라우저에서 이루어집니다. Chrome과 Edge는 동일한 DevTools를 사용하므로 단계가 동일합니다. 예를 들어, 주문 내역 페이지의 트래픽을 캡처하고 싶다고 가정해 봅시다.
- 기록하려는 페이지를 엽니다. API에 세션이 필요한 경우 먼저 로그인하세요. HAR에 해당 요청들도 포함됩니다.
- 개발자 도구를 엽니다. Windows 및 Linux에서는
F12또는Ctrl+Shift+I를 누르고, Mac에서는Cmd+Opt+I를 누릅니다. - Network 탭으로 전환합니다. 이곳에서 DevTools는 페이지에서 이루어지는 모든 요청을 나열합니다.
- 페이지를 새로고침하거나, 트래픽을 확인하고 싶은 동작들을 클릭합니다. 주문 내역 뷰를 로드하면
/api/orders,/api/orders/{id}및 페이지에 필요한 다른 모든 호출이 발생합니다. 각 호출은 한 행으로 표시됩니다. - 아무 요청 행에서 마우스 오른쪽 버튼을 클릭하고 Save all as HAR with content를 선택합니다. 예를 들어
order-history.har와 같이 파일을 저장할 위치를 선택하고 저장합니다. 메뉴 문구가 혼란스럽다면, Chrome DevTools Network 참조에서 동일한 캡처 및 내보내기 흐름을 문서화하고 있습니다.
"with content" 부분이 중요합니다. 이 옵션은 DevTools에게 요청 메타데이터뿐만 아니라 응답 본문도 포함하도록 지시합니다. 응답 본문이 없으면, 가져온 엔드포인트에는 요청 형태만 있고 예시 응답은 없을 것입니다.
브라우저를 떠나기 전에 빠른 건전성 검사를 해보세요: 텍스트 편집기에서 .har 파일을 열면 읽기 쉬운 JSON 형식임을 알 수 있습니다. 각 항목이 request 및 response 객체를 포함하는 entries 배열을 볼 수 있을 것입니다. 이것이 Apidog가 읽는 구조입니다.
한 가지 명심할 점이 있습니다. 페이지 로드는 API 호출 이상을 가져옵니다. 이미지, 스타일시트, 스크립트도 가져오며, 이 모든 것이 HAR에 포함됩니다. 브라우저에서 직접 필터링할 필요는 없습니다. Apidog는 가져올 때 이를 제외할 수 있는 스위치를 제공하며, 이에 대해서는 다음 섹션에서 다룹니다.
2단계: HAR을 Apidog로 가져오기
파일을 저장한 후, Apidog로 이동합니다. 가져오기 기능은 한 곳에 있습니다.
- 프로젝트를 열고 Settings > Import Data > Manual로 이동합니다.
- 형식을 HAR로 선택합니다.
- 방금 저장한
order-history.har와 같은.har파일을 업로드합니다.
확인하기 전에, Apidog는 세 가지 가져오기 옵션을 보여줍니다. 이 옵션들은 결과의 깔끔함을 결정하므로, 그냥 클릭하기보다는 각 옵션을 이해하는 것이 좋습니다.
옵션 1: BaseURL 처리 방식
캡처된 모든 요청은 https://api.shop.example.com/v1/orders/123과 같은 전체 URL을 가집니다. 호스트 부분에 대해 두 가지 선택지가 있습니다:
- Hardcode는 BaseURL을 각 엔드포인트의 경로 내부에 유지합니다. 모든 엔드포인트는 전체
https://api.shop.example.com접두사를 가집니다. - Remove (권장)는 BaseURL을 제거하여 엔드포인트 경로가
/v1/orders/123이 되도록 합니다. 호스트는 이후 환경 변수를 통해 전역적으로 관리됩니다.
특별한 이유가 없다면 Remove 옵션을 선택하세요. 이 설정이 권장되는 이유가 있습니다: 기본 URL이 환경 변수에 있을 때, 환경을 전환함으로써 동일한 엔드포인트를 프로덕션, 스테이징 또는 로컬 서버로 지정할 수 있으며, 엔드포인트 자체를 수정할 필요가 없습니다. 하드코딩은 모든 엔드포인트를 캡처한 호스트에 고정시키므로, 다른 서버를 대상으로 테스트해야 할 때 어려움이 따릅니다.
옵션 2: 정적 리소스 제외
이 스위치는 복잡한 엔드포인트 목록으로부터 당신을 구해줍니다. Static Resource 옵션을 Exclude로 설정하면, Apidog는 캡처된 이미지, CSS, JavaScript 파일을 건너뛰도록 지시합니다. 단일 페이지 로드로 수십 개의 이러한 파일이 생성될 수 있으며, 이들 중 어떤 것도 문서화하고 싶은 API 엔드포인트가 아닙니다.
거의 모든 가져오기에서 Exclude를 켜십시오. 필터링 후 남는 것은 실제 API 트래픽입니다: logo.png에 대한 요청이 아닌, /api/orders 및 관련 JSON 호출들입니다.
옵션 3: 엔드포인트별 테스트 케이스 생성
세 번째 옵션은 Endpoint Case Generation입니다. 이 옵션을 ON으로 설정하면 Apidog는 가져올 때 각 엔드포인트에 대한 기본 테스트 케이스를 생성합니다. 테스트 케이스는 캡처된 값이 이미 채워진 상태로 엔드포인트를 저장하고 실행할 수 있는 호출입니다.
이것은 나중에 큰 도움이 되는 작은 단계입니다. 이러한 엔드포인트를 테스트하는 것이 목표라면, 엔드포인트별로 준비된 케이스가 있다는 것은 처음부터 만들 필요 없이 즉시 실행할 수 있다는 것을 의미합니다. 지금은 문서화만 원한다면, 이 옵션을 끄고 나중에 케이스를 추가할 수 있습니다.
가져오기를 확인합니다. Apidog는 HAR을 읽고, 당신의 옵션을 적용하며, 캡처된 브라우저 상호 작용을 프로젝트 내의 API 엔드포인트로 변환합니다. 엔드포인트 트리를 열면 그룹화되고 준비된 엔드포인트들을 볼 수 있을 것입니다.
다음은 주문 호출을 예시로 사용하여 가져온 엔드포인트가 어떻게 생겼는지 대략적으로 보여줍니다:
GET /v1/orders/123
Host: api.shop.example.com
Authorization: Bearer <token-from-capture>
Accept: application/json
그리고 Apidog가 함께 저장하는 캡처된 응답입니다:
{
"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"
}
이 응답은 서버가 반환한 실제 데이터로, 모의 응답이나 테스트 검증을 위한 확실한 기반이 됩니다.
3단계: 생성된 엔드포인트 정리하기
HAR 가져오기는 빠른 초기 단계일 뿐, 완성된 API 정의는 아닙니다. 캡처된 트래픽은 본질적으로 지저분하므로, 결과를 정리하는 데 몇 분을 할애해야 합니다.
- 불필요한 부분 제거. Static Resource를 Exclude로 설정했더라도, 분석 핑, 헬스 체크 또는 관심 없는 서드파티 호출이 발견될 수 있습니다. 사용하지 않을 엔드포인트를 삭제하여 트리가 실제 API를 반영하도록 하세요.
- 이름 변경 및 그룹화. 캡처된 엔드포인트는 경로를 따라 이름이 지정되는데, 이는 기능적이지만 평면적입니다. 명확한 이름을 지정하고 (
/v1/orders/123대신 "ID로 주문 가져오기"와 같이), API 구조에 맞는 폴더로 정리하세요. - 경로 파라미터 수정.
/v1/orders/123캡처는 리터럴 경로로 가져와집니다. 만약123이 실제 주문 ID라면, 해당 세그먼트가{orderId}경로 파라미터가 되도록 엔드포인트를 수정하세요. 이 한 가지 변경으로 단일 캡처 호출이 어떤 주문에도 작동하는 재사용 가능한 엔드포인트가 됩니다. - 공유하기 전에 민감 정보 제거. 이 부분은 잊기 쉽습니다. HAR은 해당 세션에서 활성 상태였던 모든 인증 토큰을 캡처하며, 이는 헤더에 포함됩니다. 프로젝트를 커밋하거나 팀원과 공유하기 전에, 토큰을 환경 변수로 이동하고 캡처된 자격 증명을 예시에서 삭제하세요. Stripe 문서에서도 라이브 키가 공유 아티팩트로 유출되지 않도록 하는 동일한 점을 강조하며, HAR은 바로 그러한 유출을 일으킬 수 있는 아티팩트입니다.
- 본문 건전성 확인. 데이터를 예상했지만 본문이 비어있다면, "with content" 옵션 없이 내보냈을 가능성이 큽니다. Save all as HAR with content를 사용하여 다시 캡처하고 재가져오기 하세요.
엔드포인트가 정리되면, Apidog의 다른 엔드포인트와 동일하게 작동합니다. 이를 문서화하고, 각 응답에서 모의 응답을 생성하며, 테스트를 구축할 수 있습니다. Apidog에서 테스트 시나리오 작성 가이드는 여기에서 자연스럽게 이어지며, 이 엔드포인트에서 타입이 지정된 클라이언트 코드를 원한다면 Apidog로 클라이언트 코드 생성 방법을 참조하세요.
변형 및 솔직한 한계
자주 발생하는 몇 가지 상황을 언급하겠습니다.
아직 자동 레코더는 없습니다
프록시처럼 Apidog가 백그라운드에서 실시간으로 트래픽을 기록할 것이라고 예상할 수도 있습니다. 하지만 Apidog는 그렇게 하지 않으며, 이 점을 명확히 밝힐 가치가 있습니다. 문서에는 명확하게 명시되어 있습니다: “Apidog는 현재 자동 엔드포인트 기록 기능을 지원하지 않지만, 향후 지원할 계획이 있습니다.”
따라서 현재 지원되는 경로는 이 가이드에서 설명하는 것과 동일합니다: 브라우저 DevTools로 캡처하고, HAR을 내보내기한 다음 가져오는 것입니다. 문서에서 권장하는 흐름은 브라우저에서 엔드포인트를 실행하는 동안 DevTools를 열고, 완료되면 HAR을 내보내고, 한 번의 클릭으로 Apidog로 가져온 다음, 테스트 시나리오를 생성하고 모든 요청을 가져와 재생하는 것입니다. 이는 수동 캡처 단계에 이어 한 번의 클릭으로 가져오는 과정이며, 실시간 레코더가 아닙니다. 자동 기록 기능이 출시되면 이 섹션은 변경되겠지만, 그때까지 기다릴 필요는 없습니다.
Apidog 브라우저 확장 프로그램은 다른 도구입니다
Apidog 브라우저 확장 프로그램이 있으며, 이것이 HAR 트래픽을 캡처한다고 쉽게 가정할 수 있습니다. 하지만 그렇지 않습니다. 이 확장 프로그램은 데스크톱 클라이언트를 열지 않고도 브라우저에서 직접 Apidog의 API 테스트 및 디버깅 기능을 사용할 수 있게 합니다. 이는 요청을 실행하는 것이지 기록하는 것이 아닙니다.
HAR 캡처는 전적으로 브라우저 자체의 DevTools에서 이루어집니다. 만약 테스트를 위해 확장 프로그램을 사용한다면, 브라우저가 다음과 같은 제한을 가한다는 것을 알아두세요: Cookie, Host, Origin, Content-Length와 같은 특정 헤더를 차단하고, GET 또는 HEAD 요청 시 본문을 전송하지 않으며, 로컬 코드나 머신 뒤의 데이터베이스에 도달할 수 없습니다. 가져오기 위한 트래픽 캡처에는 DevTools 및 HAR 내보내기를 고수하세요. 완전한 헤더 제어가 필요한 더 복잡한 디버깅에는 Apidog 데스크톱 클라이언트가 브라우저에 의해 부과되는 이러한 제한이 없습니다.
다른 형식도 동일하게 가져오기 가능
HAR은 동일한 Settings > Import Data > Manual 화면에서 허용하는 여러 형식 중 하나입니다. 이미 OpenAPI 또는 Swagger 파일이 있다면, 캡처보다 더 깔끔한 결과를 얻을 수 있습니다. 스펙은 의도적으로 구조화되기 때문입니다. Swagger API 문서를 Apidog로 마이그레이션하는 방법에 대한 우리의 설명은 그 경로를 다루며, Postman에서 전환하는 경우에도 Postman 환경 및 컬렉션 마이그레이션 가이드가 동일한 작업을 다룹니다. 실제 스펙이 존재하지 않고 캡처된 트래픽이 당신이 가진 최상의 기록일 때 HAR을 사용하세요.
Apidog CLI로 워크플로 자동화하기
HAR 가져오기는 GUI 단계일 필요는 없습니다. Apidog CLI에는 HAR 파일을 직접 읽는 import 명령어가 있습니다. 이는 캡처가 서버에서 발생하거나, 파이프라인에서 가져오기를 스크립트하거나, AI 코딩 에이전트가 캡처를 엔드포인트로 전환하게 할 때 유용합니다:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
# Turn a captured HAR into endpoints in your project
apidog import --project <PROJECT_ID> --format har --file ./capture.har
--format 플래그는 openapi, postman, wsdl, insomnia 등도 허용하므로, 하나의 명령으로 대부분의 가져오기 소스를 처리할 수 있습니다. 엔드포인트가 존재하고 이를 테스트 시나리오에 저장했다면, 해당 시나리오를 CI에서 헤드리스 모드로 실행하세요:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t <SCENARIO_ID> -e <ENV_ID> -r cli
여기서 -t는 저장된 테스트 시나리오 ID이고, -e는 환경 ID(BaseURL을 담고 있는 동일한 환경 변수)이며, -r은 콘솔 출력을 위한 리포터 cli를 선택합니다. Apidog에서 테스트 시나리오 작성 가이드를 따라 시나리오를 구축한 다음, Apidog CLI CI/CD 가이드를 사용하여 두 명령을 파이프라인에 연결하세요.
자주 묻는 질문 (FAQ)
어떤 브라우저가 HAR 파일을 내보낼 수 있나요?
DevTools를 사용하는 모든 Chromium 기반 브라우저는 동일한 방식으로 작동합니다. 따라서 Chrome과 Edge 모두 Network 탭과 Save all as HAR with content 메뉴 항목을 사용합니다. Apidog 문서는 Chrome 및 Edge 경로를 구체적으로 다룹니다. 다른 브라우저는 자체 내보내기 메뉴를 가지고 있지만, 레이블이 다를 수 있으므로 브라우저 자체의 DevTools 용어에 맞춰 확인하세요.
가져온 엔드포인트 목록이 너무 많습니다. 무엇이 잘못되었나요?
Static Resource 설정을 모든 것을 포함하도록 남겨두었을 가능성이 큽니다. 페이지 로드는 이미지, CSS, 스크립트를 가져오며, 이 모든 것이 HAR에 포함됩니다. Static Resource 옵션을 Exclude로 설정하여 파일을 다시 가져오면 목록이 실제 API 호출로 줄어듭니다. 또한, 남은 것들을 수동으로 삭제할 수도 있습니다.
BaseURL에 대해 Hardcode와 Remove 중 무엇을 선택해야 하나요?
거의 모든 경우에 Remove (권장)를 선택하세요. 이 옵션은 각 엔드포인트 경로에서 호스트를 추출하여 환경 변수를 통해 전역적으로 관리할 수 있도록 합니다. 이를 통해 엔드포인트를 수정하지 않고도 프로덕션, 스테이징, 로컬 환경을 전환할 수 있습니다. Apidog의 테스트 시나리오가 실행될 때 이와 동일한 설정을 읽습니다. 전체 URL이 각 경로에 고정되기를 특별히 원하는 경우에만 Hardcode를 선택하세요.
HAR에 제 인증 토큰이 포함되나요?
네, 그리고 그것이 문제입니다. HAR은 세션 중에 전송된 실제 헤더를 기록하므로, 활성 상태였던 모든 베어러 토큰이나 쿠키가 파일에 포함됩니다. HAR을 비밀처럼 다루세요: 공개 이슈에 붙여넣지 말고, 가져온 후에는 자격 증명을 환경 변수로 이동하고 프로젝트를 공유하기 전에 저장된 예시에서 해당 정보를 지우세요.
GUI를 건너뛰고 명령줄에서 HAR을 가져올 수 있나요?
네. Apidog CLI의 apidog import --project <id> --format har --file <path> 명령은 앱을 열지 않고 HAR을 프로젝트로 가져옵니다. 이는 캡처가 서버에서 또는 CI 작업 내에서 발생할 때 유용합니다. GUI는 여전히 일회성 캡처를 위한 대화형 가져오기 옵션(BaseURL 처리, 정적 리소스 필터링)을 제공하므로, 필요에 따라 선택하세요: 스크립트 또는 에이전트 기반 가져오기에는 CLI를, 수동으로 가져오기를 조정하고 싶을 때는 GUI를 사용하십시오. 가져온 후 apidog run은 해당 엔드포인트로 구축한 테스트 시나리오를 다시 재생합니다.
마무리
HAR 파일은 눈에 보이는 트래픽과 재사용 가능한 엔드포인트를 연결하는 다리입니다. 브라우저의 DevTools에서 Save all as HAR with content로 세션을 캡처하고, Settings > Import Data > Manual을 통해 BaseURL에 대해 Remove를, Static Resource를 Exclude로 설정하여 가져온 다음, 몇 분 동안 이름을 변경하고, 파라미터화하고, 민감 정보를 제거하는 데 시간을 할애하세요. 그렇게 하면 문서화하고, 모의 응답을 생성하며, 테스트할 수 있는 작동하는 엔드포인트 세트를 얻을 수 있습니다.
다음 캡처를 실제 엔드포인트로 전환할 준비가 되셨나요? Apidog를 다운로드하여 신용카드 없이 무료로 사용해 보세요.