api-endpoint-mapper

# API Endpoint Mapper

Scans your entire codebase to find every API endpoint definition and every API call, then shows you exactly what's connected, what's broken, and what's probably a typo.

## Quick Start

python scripts/scan\_endpoints.py /path/to/your/project

Outputs API-ENDPOINT-REPORT.md in the project root.

## What It Finds

### Backend Endpoint Definitions

- Express routes: app.get('/api/users'), router.post('/sensors')

- Next.js/file-based routes: pages/api/\*, app/api/\*

- Route handlers with path patterns

- WebSocket endpoints

### Frontend API Calls

- fetch('/api/...')

- axios.get/post/put/delete(...)

- Custom API clients

- WebSocket connections

- Environment variable URLs

## Report Structure

The generated report contains:

\# API Endpoint Report



\## Summary

\- Backend endpoints: X

\- Frontend calls: Y  

\- Matched: Z

\- UNMATCHED CALLS (BROKEN): N  ← These are your immediate problems

\- Unused endpoints: M

\- Potential typos: P



\## 🚨 BROKEN: Frontend Calls With No Backend

These calls will fail - no endpoint exists:

| Frontend Call | File:Line | Closest Match | Similarity |

|---------------|-----------|---------------|------------|



\## ⚠️ Potential Typos

These look like they should match but don't:

| Frontend | Backend | Difference |

|----------|---------|------------|



\## 📡 All Backend Endpoints

| Method | Path | File:Line | Called By |

|--------|------|-----------|-----------|



\## 📱 All Frontend Calls  

| Method | Path | File:Line | Matches |

|--------|------|-----------|---------|



\## 🔌 WebSocket Connections

| Event/Channel | Emitter | Listeners |

|---------------|---------|-----------|

## Usage Patterns

### Full project scan

python scripts/scan\_endpoints.py .

### Specific directories

python scripts/scan\_endpoints.py . --frontend src/client --backend src/server

### Include node_modules API patterns (if using SDK)

python scripts/scan\_endpoints.py . --include-modules

### JSON output for programmatic use

python scripts/scan\_endpoints.py . --json > endpoints.json

## Fixing Mismatches

When the report shows broken calls:

1. **Check the "Closest Match" column** - often it's a typo

2. **Check method mismatches** - GET vs POST on same path

3. **Check path parameter differences** - /users/:id vs /users/${id}

4. **Check base URL differences** - /api/v1/ vs /api/

## Before Refactoring

Run this BEFORE renaming any endpoints. After changes:

1. Run again

2. Compare reports

3. Ensure no new broken calls appeared

## Configuration

Create .endpoint-mapper.json in project root for custom patterns:

{

  "backendPatterns": \[

    "customRouter\\\\.(get|post)\\\\(\['\\"](\[^'\\"]+)"

  ],

  "frontendPatterns": \[

    "apiClient\\\\.(get|post)\\\\(\['\\"](\[^'\\"]+)"

  ],

  "ignorePaths": \[

    "/health",

    "/metrics"

  ],

  "baseUrlEnvVars": \[

    "REACT\_APP\_API\_URL",

    "NEXT\_PUBLIC\_API\_URL", 

    "VITE\_API\_URL"

  ]

}