네트워크 노가다 끝! browser-to-api로 API 역설계하기

네트워크 노가다 끝! browser-to-api로 API 역설계하기

1. 어떻게 작동하나요?

개발자라면 한 번쯤 네트워크 탭을 켜놓고 일일이 복사-붙여넣기 하느라 고생한 적이 있을 겁니다. browser-to-api는 이 과정을 완전히 자동화해주는 강력한 도구예요.

• browser-trace (기록): 브라우저에서 일어나는 모든 요청과 이벤트를 .jsonl 파일로 담아냅니다.
• browser-to-api (분석): 기록된 데이터를 읽어 URL 템플릿과 데이터 타입을 추론해 OpenAPI 문서를 생성합니다.

2. 실전 사용 가이드

단계 1: 트래픽 캡처 (Capture)

# 네트워크 본문 캡처 활성화 권장
browse network on

# 대상 사이트에서 실제 기능을 수행하여 데이터를 쌓습니다.
browse open https://example.com

단계 2: API 스펙 생성 (Generate)

수집된 데이터를 분석 엔진(discover.mjs)에 돌려주기만 하면 됩니다.

node scripts/discover.mjs --run .o11y/my-site

단계 3: 결과 확인 (Review)

생성된 index.html을 열면 시각화된 보고서를 바로 확인할 수 있습니다.

3. 똑똑한 분석 기능들

• 노이즈 필터링: 광고 트래커나 분석 도구(GA 등)를 자동으로 걸러내어 순수 API 트래픽만 남깁니다.
• GraphQL 대응: 같은 엔드포인트라도 operationName에 따라 개별 API로 똑똑하게 분리합니다.
• 지능형 템플릿: ID나 UUID 같은 변수를 인식해 {id} 형태의 경로 파라미터로 변환합니다.

4. 무엇이 만들어지나요?

분석이 끝나면 .o11y/my-site/api-spec/ 폴더에 다음 파일들이 생깁니다.

• index.html: SDK 샘플이 포함된 시각화 보고서
• openapi.yaml: Postman 등에서 즉시 사용 가능한 표준 규격서
• client.mjs: 즉시 사용 가능한 Fetch 기반 클라이언트 코드

5. 더 잘 쓰는 팁

더 정확한 스펙을 얻고 싶다면 브라우저에서 최대한 다양한 옵션을 선택하며 트래픽을 많이 발생시키는 게 중요합니다. 또한, --origins 플래그를 사용해 특정 도메인만 지정하면 분석 속도가 훨씬 빨라져요.

주의사항: 인증 헤더 등이 포함될 수 있으니, 공유 전 민감 정보 유무를 꼭 확인하세요!