ApiCatcher 핵심 기능 소개 및 사용 상황

ApiCatcher는 iOS, Android, macOS, Windows용 HTTP/HTTPS 캡처·디버깅 도구입니다. 휴대폰에서는 기기 안의 VPN으로 트래픽을 받으므로, 컴퓨터를 프록시로 둘 필요가 없습니다. 데스크톱에서는 시스템 프록시와 TUN을 바꿔 쓸 수 있습니다. TUN은 시스템 프록시를 보지 않는 앱을 잡기 위한 모드입니다.

이름의 Api는 처음부터 풀고 싶었던 일입니다. 캡처한 요청을 기록 한 줄로 끝내지 않고, 이어서 쓸 수 있는 API로 만드는 것입니다. 아래 여덟 가지는 각각 어떤 문제를 푸는지, 그리고 대응하는 사용 상황입니다.

캡처

이후 기능의 시작점입니다. 켜면 앱이나 브라우저의 HTTP/HTTPS가 로컬 프록시를 통과합니다. CA 인증서를 설치하고 신뢰하면 HTTPS 내용을 볼 수 있습니다. WebSocket 핸드셰이크와 프레임도 남고, 프레임은 대화 목록처럼 쌓입니다. JSON은 색으로 구분되고, Payload로도 검색할 수 있습니다.

같이 쓰는 기능:

• 허용·차단 목록: Host로 거릅니다. 허용 목록이 비어 있지 않으면 일치하는 Host만 남습니다. 차단 목록의 Host는 기록하지 않습니다. *를 쓸 수 있습니다. 예: *.example-api.com.
• 세션: 시작부터 중지까지가 한 세션입니다. 그 번의 캡처만 보거나, 그 세션을 통째로 지울 수 있습니다.
• 검색: URL, 요청 헤더, 응답 헤더, 요청 Body, 응답 Body를 찾습니다. 메서드, 프로토콜, Content-Type, 상태 코드, 시간 범위로도 거릅니다.
• 내보내기: 한 건은 Raw, cURL, Markdown으로, 여러 건은 HAR로 내보냅니다. 이미지, 동영상, 오디오는 따로 모이고, Range 조각은 합친 뒤 내보냅니다.

사용 상황：API 문제 분석. 실패한 동작을 한 번 더 하고, 기록에서 그 요청을 엽니다. 클라이언트가 실제로 보낸 URL, Header, Body와 서버가 돌려준 상태 코드, 응답 Body를 대조합니다. 요청 자체가 잘못됐으면 클라이언트 문제이고, 요청은 맞는데 응답이 틀리면 서버 문제입니다. 어느 쪽인지 먼저 가른 다음 더 봅니다.

사용 상황：기능이 사용하는 API 확인. 그 기능을 서로 다른 업무 시나리오마다 한 번씩 조작합니다. 캡처 기록만 봐도 어떤 API를 쳤는지, 상황마다 파라미터가 어떻게 다른지 알 수 있습니다.

API 문서 자동 생성

조건에 맞는 HTTP/HTTPS는 Host별로 API 문서가 됩니다. API의 키는 「메서드 + Host + Path」입니다. 같은 API를 여러 번 잡아도 Query, Header, Body는 아직 나오지 않은 필드만 추가합니다. 이미 있는 필드 이름을 나중 요청으로 덮어쓰지 않습니다. 응답 예시는 상태 코드가 200일 때만 갱신됩니다.

Host 전체, API 하나, 또는 API 즐겨찾기에서 내보낼 수 있습니다. 대상은 Postman, Apifox, 또는 Bruno ZIP입니다.

사용 상황：API 관리 도구로 내보내기. 문서가 생기면 Host 전체, API 하나, 또는 즐겨찾기 폴더를 Postman, Apifox, Bruno로 보내 거기서 고치고 공유합니다.

HAR를 내보내 Postman 등 API 관리 도구로 가져와 API를 만드는 방식과 달리, ApiCatcher가 생성하는 API 문서는 캡처가 더 많은 업무 시나리오를 거칠수록 필드가 보강되어 점점 완전해집니다.

요청 재생

재생은 ApiCatcher가 다시 클라이언트가 되는 일입니다. 기록에서 HTTP/HTTPS 하나를 꺼내 쿼리, 헤더, Body를 바꾸거나 그대로 서버에 보내고, 재생 화면에서 상태 코드와 응답을 봅니다. 이 재생 때문에 앱 화면이 새로고침되지는 않습니다. WebSocket은 여기서 다시 연결하고, 프레임을 직접 보내 상대 응답을 봅니다.

캡처가 켜져 있으면 재생은 로컬 프록시를 지나므로, 이미 넣은 Rewrite와 스크립트가 적용되고 기록에도 다시 남습니다.

사용 상황：API 연동 조율. 백엔드가 API를 고친 뒤, 또는 원인 추적용 로그를 넣은 뒤, 방금 잡은 요청을 한 번에 다시 보냅니다. 한 번이면 고쳐졌는지 알 수 있고, 그 요청이 새 로그에도 남습니다.

콤보 재생

여러 HTTP/HTTPS를 캔버스에 올려 의존 관계대로 실행합니다. 서로 의존하지 않는 노드는 병렬입니다. 의존이 있으면 직렬이고, 이전 단계가 모두 성공한 다음에야 다음 단계가 실행됩니다.

자주 쓰는 편집은 네 가지입니다.

사용 상황：호출 체인 연동 조율. 뒤 요청은 앞 응답을 써야 합니다. 하류에 의존을 걸고, 상류 응답을 하류 요청에 주입한 뒤 그 순서로 실행합니다. 예를 들어 GET /user는 POST /login에 의존하고, POST /order는 GET /user에 의존합니다. 뒤의 둘에는 token을 Authorization에 넣고, 로그인, 사용자 정보, 주문 순으로 실행됩니다.

사용 상황：동일 API·다양한 입력 테스트. 그 요청을 여러 번 추가합니다. 차례로 실행하려면 노드를 한 줄로 잇습니다. 의존만 걸고 주입은 넣지 않습니다. 노드마다 미리 넣은 Body로 실행한 뒤 결과를 비교합니다. 예를 들어 로그인을 세 번 넣고, Body는 정상 계정, 틀린 비밀번호, 빈 비밀번호로 둡니다.

Rewrite

요청이 업무 서버에 닿기 전, 또는 응답이 앱으로 돌아오기 전에 규칙으로 트래픽을 바꿉니다. 규칙은 범위와 동작입니다. 범위는 Host이고, Path와 Method는 선택입니다.

동작:

• 리다이렉트: 운영 도메인을 내 컴퓨터나 스테이징으로 보냅니다.
• Mock: 실제 요청을 보내지 않고, 정해 둔 상태 코드, 헤더, Body를 돌려줍니다.
• 요청 버리기 / 응답 버리기: 나가지 않는 요청, 또는 서버가 답하지 않는 상황을 만듭니다.
• 지연: 응답을 늦춰, 느린 망에서 로딩과 시간 초과가 어떻게 보이는지 확인합니다.
• 수정: 헤더를 고치거나 Body를 통째로 바꾸거나, 정규식으로 Body 안을 찾아 바꿉니다. 정규식은 원하는 결과를 말로 적으면 AI가 만듭니다.

사용 상황：API Mock. 백엔드가 아직 없거나, 클라이언트를 특정 상태로 보내고 싶을 때 실제 요청 없이 정해 둔 상태 코드와 Body를 돌려줍니다. 예를 들어 주문 목록에 결제 대기와 완료 두 상태를 넣고 화면을 먼저 만든 뒤, API가 준비되면 규칙을 끕니다.

사용 상황：응답 수정. 필드 몇 개만 바꿔 클라이언트가 이어서 어떻게 동작하는지 봅니다. 서버 데이터는 건드리지 않습니다. 예를 들어 정규식으로 "balance": 100을 "balance": 0으로 바꿔, 잔액이 없을 때 버튼이 어떻게 비활성되는지 봅니다.

스크립트

매번 값이 달라지면 고정 규칙으로는 부족합니다. JavaScript를 씁니다. 일치한 요청은 interceptRequest로, 응답은 interceptResponse로 들어갑니다. 직접 쓰거나, AI에게 맡기거나, 팀이 나눠 주는 LAN 스크립트 URL을 넣어도 됩니다.

스크립트에서 바로 쓸 수 있는 것:

• crypto: MD5, SHA, HMAC, Base64. 서명이나 Body 암복호화에 씁니다.
• localStore: 요청을 넘어 Token 같은 상태를 저장합니다.
• httpClient: 스크립트 안에서 HTTP를 한 번 더 보냅니다. Token이 만료되면 먼저 로그인한 뒤 넣는 식입니다.

사용 상황：요청 동적 계산. 서명과 타임스탬프는 매번 다르므로, 고정 문자열 치환으로는 안 됩니다. 이번 요청으로 계산한 뒤 통과시킵니다. 예를 들어 재생이 계속 401이면, 현재 시각과 Body로 HMAC을 만들어 X-Timestamp와 X-Signature에 넣습니다. 재생 전에 캡처를 켜 두지 않으면 스크립트는 이 요청에 적용되지 않습니다. 캡처가 꺼져 있으면 스크립트는 실행되지 않습니다.

사용 상황：Body 암호화·복호화. 사내 시스템은 Body를 한 번 더 암호화하는 경우가 많습니다. HTTPS를 풀어도 암호문이 보입니다. 보내기 전에 암호화하고, 돌아온 뒤 복호화해야 평문을 읽고 고칠 수 있습니다. 예를 들어 interceptResponse에서 응답 Body를 풀어 보고, 재생할 때는 interceptRequest에서 고친 평문을 다시 암호화해 보냅니다. 재생 전에 캡처를 켜야 스크립트가 실행됩니다.

DNS 바꾸기

제품 안의 이름은 DNS 매핑입니다. 프록시 계층에서 DNS를 바꿉니다. 시스템 hosts도, Wi-Fi DNS도 건드리지 않습니다. 캡처가 켜져 있으면 규칙에 맞는 연결은 공인 DNS를 건너뛰고, 적어 둔 IP로 바로 TCP를 엽니다. HTTP Host와 TLS SNI는 원래 도메인 그대로라 앱은 알아채지 못합니다. *.apicatcher.net 같은 와일드카드도 됩니다.

사용 상황：동일 도메인으로 테스트·스테이징 전환. 테스트, 스테이징, 운영은 같은 도메인을 씁니다. 테스트나 스테이징으로 가려면 그 도메인이 가리키는 곳을 바꿉니다. DNS 매핑에서 테스트 또는 스테이징 IP를 넣으면 캡처를 시작하는 순간 적용됩니다. Wi-Fi DNS를 매번 바꿀 필요가 없고, 시스템 DNS 캐시와도 싸우지 않습니다.

예약 실행

요청 재생 하나, 또는 콤보 재생 전체를 정해 둔 때에 실행합니다. 일정은 두 가지입니다.

• Cron: 필드 6개, 순서는 「초 분 시 일 월 요일」입니다. 0 * * * * ?는 매분 0초입니다. 문법이 헷갈리면 하고 싶은 일을 말로 적어 AI에게 맡깁니다.
• 사용자 지정: 초 간격으로 반복하고, 횟수나 지속 시간을 제한할 수 있습니다.

자동 종료 조건에 맞으면 작업이 멈춥니다. 실행 기록에서 걸린 시간과 성공률을 볼 수 있습니다. 휴대폰에서는 캡처를 먼저 켜야 작업이 실행됩니다. 데스크톱은 앱이 열려 있으면 실행됩니다.

사용 상황：예약 제출. 시간이 짧아 직접 누르면 놓치기 쉽습니다. 요청 하나 또는 콤보 재생을 간격대로 자동 실행하고, 응답 내용으로 멈춥니다. 예를 들어 세일 시작 몇 초 전부터 1초마다 주문을 넣고, code가 200이거나 Body에 구매 성공·행사 종료가 보이면 멈춥니다.

사용 상황：정기 점검. 같은 API를 반복해서 불러 살아 있는지, 느려졌는지 봅니다. 헬스 체크라면 Cron 0 * * * * ?로 1분에 한 번입니다. 자동 종료는 두지 않고, 실행 기록의 P95를 봅니다.

사용 상황：정기 회귀 테스트. 이미 짜 둔 콤보 재생을 일정대로 반복해, 결과가 아직 기대와 같은지 봅니다. 콤보 재생에서 같은 API를 여러 번 넣고, 노드마다 다른 입력을 미리 넣습니다. 그 노드들이 테스트 케이스입니다. 이 콤보를 일주일에 한 번 실행합니다. 먼저 로그인이 필요하면 로그인 요청을 하나 넣어, 나머지 모든 요청의 공통 선행으로 둡니다. 로그인 외의 요청끼리는 병렬로만 실행됩니다.

자세한 절차는 문서에 있습니다. 사용자 매뉴얼, Rewrite, 스크립트, 콤보 재생, 예약 실행.

위 기능이 ApiCatcher 전부는 아닙니다. 더 많은 기능은 공식 웹사이트에서 확인할 수 있습니다. 글에 든 사용 상황도 이 경우에만 쓸 수 있다는 뜻이 아니라, 각 기능을 만들 때 처음 풀려고 했던 문제를 예로 든 것입니다.