Ever been handed an API with zero documentation and asked to figure it out? We’ve been there. Our team has developed a battle-tested approach to turn these documentation black holes into clear, comprehensive API specs. Here’s how we reverse engineer APIs.
Starting from Zero
Picture this: A client comes to you with their API, and there’s no documentation, just some endpoints that “work somehow.” Your mission? Document everything. It’s like being handed a puzzle box without the picture – but we’ve got a system for solving it.
Our Four-Step Process
1. Capture Everything That Moves
First things first – we need to see the API in action. Think of it as setting up traffic cameras to watch how the API behaves in the wild. Here’s what we use:
For Web Apps: Chrome extension by Andrew Walsh that capture API calls as they happen and builds an OpenAPI spec document. This is perfect for watching how the frontend talks to the backend and the action flows, and shows us exactly what headers, path, payload and query parameters goes back and forth
For Mobile Apps: Burp Suite becomes our best friend, it acts like a man in the middle, and intercepts all those API calls your phone is making to private APIs. If you’ve ever wondered how people make wrapper APIs for Apps without public APIs and list them on marketplaces – this is it
For Everything Else: HTTPToolkit is our Swiss Army knife, it records every single API interaction, and gives us the full picture of what’s happening and allows testing and fuzzing of endpoints
2. Turn Traffic into Documentation
Now comes the cool part. We take all that captured traffic and automatically generate a basic OpenAPI doc. It’s like turning security camera footage into a map:
- Converts captured requests/responses into OpenAPI format.
- Defines the security and authentication headers used.
- Establishes initial endpoint documentation.
- Creates preliminary entity schema definitions.
- Identifies common patterns across endpoints.
3. Poke It Until It Breaks (Safely)
This is where it gets interesting. We systematically test the API to find its limits:
- What happens if we send empty fields?
- How does it handle weird characters?
- Where are the payload size limits?
- What breaks it, and how does it fail?
Taking this, along with API fuzzing becomes crucial for understanding security boundaries and validation rules. Fuzzing an API simply means sending different input values to endpoints to uncover potential vulnerabilities or any unexpected behavior. We even maintain word lists for some endpoint and server types that we’ve seen evoke interesting responses!
Systematic Testing
- Probing endpoint limitations
- Testing various input combinations
- Documenting validation rules
- Identifying required vs. optional fields
Security Assessment
- Understanding authentication requirements
- Documenting authorization levels & any RBAC indicators
- Identifying rate limiting patterns – soft or hard.
- Noting security-related headers
Each response teaches us something new about how the API works, and we add it to our growing documentation.
4. Polish and Perfect
The final stage is where human expertise meets AI assistance, and utilizes modern development tools for thorough review and enhancement:
VSCode Integration
Using VSCode with specialized extensions like Redocly enables:
- OpenAPI syntax validation
- Schema completeness checks
- Documentation formatting
- Real-time preview capabilities
AI-Assisted Enhancement
Leveraging AI tools like GitHub Copilot and Claude helps:
- Generate comprehensive examples
- Identify missing edge cases
- Improve documentation clarity
- Suggest additional scenarios to test
Making It Work in Real Life
Keep the Client in the Loop by:
- Regular check-ins about what we’ve found
- Verify our assumptions
- Flag any security concerns immediately
- Get clarification on unusual behaviors
Test Everything:
- Multiple environments
- Different auth levels
- Various error scenarios
- All the example code we write
Quality Checks
Before we call it done, we ensure:
- Every endpoint is thoroughly tested
- All response codes are documented
- Authentication flows are crystal clear
- Rate limits and quotas are spelled out
- Examples actually work
Don’t forget about Client Communication
Be sure to keep them in the loop, whilst the original developers of the API might be gone, they could still be some institutional knowledge around edge-cases or email support threads with customers to reference. So:
- Maintain regular communication about discovered behaviors
- Verify assumptions about intended functionality
- Document any security concerns discovered
- Confirm edge case handling
The End Result
What started as a mystery API becomes a well-documented system that:
- New developers can understand quickly
- Has clear examples for every endpoint
- Shows exactly what to expect
- Includes proper error handling
- Explains security requirements
Wrapping Up
Reverse engineering APIs might sound intimidating, but with the right approach, it’s a systematic process that yields reliable results. The key is being methodical, thorough, and always verifying your findings.
Remember: Good API documentation tells a story. It’s not just about what endpoints exist, but rather it’s about how to use them successfully. Our process ensures we uncover and tell that story completely.
Need to document your undocumented API? Now you know our secrets. Just remember: capture, convert, test, and polish. Works every time. Also, we are here to help, reach out for free consultation.
