endpoint-exploration

name	endpoint-exploration
description	Document REST API endpoints through systematic empirical testing. Analyzes URL structure, generates minimal test cases, executes requests, and produces concise API documentation. Use when exploring undocumented APIs, reverse-engineering endpoints, or creating integration documentation.
allowed-tools	Bash, Read, Write, Edit, Glob, Grep

Endpoint Exploration

Create comprehensive API endpoint documentation through systematic empirical testing.

Process

Copy this checklist and track your progress:

Endpoint Exploration Progress:
- [ ] Step 1: Analyze URL structure
- [ ] Step 2: Identify parameters and types
- [ ] Step 3: Generate minimal test cases
- [ ] Step 4: Execute tests and save samples
- [ ] Step 5: Analyze response patterns
- [ ] Step 6: Write documentation
- [ ] Step 7: Review for redundancy and clarity

1. URL Analysis

Parse the URL to identify path parameters (e.g., {id}, {format}) and endpoint structure.

Do not make assumptions about what the API does - focus only on the URL structure.

2. Parameter Identification

For each parameter identified:

• Determine likely type from URL structure
• List normal values (valid inputs)
• List invalid values (wrong types, edge cases)
• Note if parameter appears optional vs required

3. Test Case Generation

Create a minimal test set covering:

• Valid cases: 1-2 examples with real data
• Format variations: If format is a parameter, test each option
• Edge cases: Boundary values (0, 1, very large numbers, leading zeros)
• Invalid cases: Wrong types, negative values, unsupported formats
• Header tests: Accept header variations, conflicts
• HTTP method tests: POST, PUT, DELETE (if GET endpoint)
• Query parameter tests: Test if query params work

Avoid redundancy: If multiple values test the same behavior, pick one.

4. Sample Collection

Execute tests and save full HTTP responses (headers + body) to samples/ directory:

• Use curl -i to capture headers
• Number files sequentially: 01-description.ext, 02-description.ext
• Use descriptive names indicating what each test validates

5. Response Analysis

For each unique response pattern, document:

• HTTP status code
• Content-Type header
• Response structure
• Any caching or rate-limit headers
• Error message formats

Identify:

• How to detect success vs failure
• How to distinguish different error types
• Any quirks (e.g., 200 for not-found, different error messages)

6. Documentation Writing

Create endpoint-documentation.md following the template structure with these sections:

Required sections:

• Endpoint (HTTP method + full URL)
• Authentication (if any)
• Parameters (path, headers, query - if applicable)
• Response Codes (table format)
• Response Structure (tables preferred over examples)

Include only if discovered:

• Caching behavior
• Format selection rules
• Special detection logic (e.g., how to tell if resource exists)
• Important quirks or edge cases

Avoid:

• Speculation or assumptions
• Redundant information (each fact appears once)
• Examples that just repeat table/prose information
• Over-documentation of obvious behavior

7. Iterative Refinement

Review documentation against this checklist:

• Redundancy: Each fact appears exactly once
• Evidence: Only documented tested behavior
• Clarity: Concise, no unnecessary detail
• Completeness: All discoveries documented

Remove sections that don't add unique value.