import requests
import json
from collections import defaultdict

class APISpeculationEngine:
    """
    Automatically discovers API endpoints by analyzing patterns
    in successful and failed requests
    """
    
    def __init__(self, base_url):
        self.base_url = base_url
        self.discovered_endpoints = defaultdict(dict)
        self.error_patterns = []
    
    def speculate_endpoint(self, endpoint_guess, method='GET'):
        """
        Try an endpoint and learn from the response
        """
        url = f"{self.base_url}/{endpoint_guess}"
        
        try:
            response = requests.request(method, url)
            
            if response.status_code == 200:
                # Valid endpoint discovered
                self.discovered_endpoints[endpoint_guess] = {
                    'method': method,
                    'response': response.json(),
                    'status': 'verified'
                }
                return True, response.json()
            
            elif response.status_code == 404:
                # Learn from 404 patterns
                self.error_patterns.append({
                    'endpoint': endpoint_guess,
                    'error': 'Not found',
                    'pattern': endpoint_guess.split('/')
                })
                return False, None
            
            else:
                # Other status codes might indicate different patterns
                self.discovered_endpoints[endpoint_guess] = {
                    'method': method,
                    'status_code': response.status_code,
                    'status': 'needs_verification'
                }
                return False, None
                
        except Exception as e:
            self.error_patterns.append({
                'endpoint': endpoint_guess,
                'error': str(e)
            })
            return False, None
    
    def generate_documentation(self):
        """
        Generate API documentation from discovered endpoints
        """
        docs = {
            'base_url': self.base_url,
            'verified_endpoints': {},
            'potential_endpoints': {},
            'common_patterns': self._analyze_patterns()
        }
        
        for endpoint, data in self.discovered_endpoints.items():
            if data['status'] == 'verified':
                docs['verified_endpoints'][endpoint] = {
                    'method': data['method'],
                    'example_response': data['response']
                }
            else:
                docs['potential_endpoints'][endpoint] = data
        
        return json.dumps(docs, indent=2)
    
    def _analyze_patterns(self):
        """
        Analyze error patterns to suggest better endpoint guesses
        """
        # Implementation for pattern analysis
        patterns = defaultdict(int)
        for error in self.error_patterns:
            if 'pattern' in error:
                for segment in error['pattern']:
                    patterns[segment] += 1
        return dict(patterns)

The Problem: When API Docs Are Just Creative Writing Exercises

Let's be honest: most API documentation falls into one of three categories. There's the "minimalist" approach (three endpoints documented, 47 discovered through brute force), the "aspirational" version (documents endpoints that were planned but never implemented), and my personal favorite: the "cryptic haiku" style where each endpoint description is exactly three words and none of them are verbs.

Why does this problem persist? Because writing documentation is like flossing: everyone knows they should do it, nobody enjoys it, and we all pretend we're doing it more than we actually are. The result? Developers become digital archaeologists, piecing together API structures from error messages, Stack Overflow answers from 2018, and the faint memory of that one intern who might have known something about it before they quit.

The absurdity reaches its peak when you find yourself doing things like:

• Testing 14 variations of /api/v1/users/{id}/profile because the docs said "profile endpoint" but didn't specify singular or plural
• Discovering that GET /data returns XML but GET /data/ (with trailing slash) returns JSON, because consistency is for cowards
• Realizing the "comprehensive examples" section was copied from a completely different API and nobody noticed for three years

The Solution: Automated Speculation Beats Manual Desperation

I built API Speculation Engine to solve this exact problem. Instead of you spending hours guessing endpoint structures, the tool does the guessing for you—but with actual logic and learning capabilities. It's like having a junior developer who's really good at pattern recognition and never takes coffee breaks.

Here's how it works: you give it a base URL, and it starts making educated guesses about endpoint structures based on common REST patterns, URL conventions it's seen before, and sheer statistical probability. It generates curl commands for the most likely endpoints, tries them out, and learns from the responses. When it hits a 404, it doesn't just give up—it learns from it and adjusts future guesses. It's Darwinism for API discovery.

The best part? It produces "probable documentation" in markdown format, complete with confidence scores. That documentation is often more accurate and useful than the "official" documentation, because it's based on what the API actually responds to, not what some overworked developer promised their PM they'd document two years ago.

How to Use It: From Installation to Speculation

Getting started is easier than convincing your product manager that "undocumented feature" isn't the same as "bug." First, clone the repository:

git clone https://github.com/BoopyCode/api-speculation-engine-1767533881
cd api-speculation-engine-1767533881
pip install -r requirements.txt

Then run it with your target API base URL:

python speculate.py --base-url https://api.questionable-service.com/v1

Here's a snippet from the main speculation logic that shows how it generates educated guesses:

def generate_endpoint_guesses(base_url):
    """Generate educated guesses about API endpoints"""
    common_patterns = [
        '/users', '/users/{id}', '/users/{id}/profile',
        '/products', '/products/{id}', '/orders',
        '/auth/login', '/auth/logout', '/settings'
    ]
    
    guesses = []
    for pattern in common_patterns:
        confidence = calculate_confidence(base_url, pattern)
        if confidence > 0.3:  # Only include decent guesses
            guesses.append({
                'endpoint': pattern,
                'confidence': confidence,
                'curl': generate_curl_command(base_url + pattern)
            })
    return sorted(guesses, key=lambda x: x['confidence'], reverse=True)

Check out the full source code on GitHub to see all the clever ways it avoids your manual suffering.

Key Features: What Makes This Tool Actually Useful

• Analyzes API base URL and makes educated guesses about endpoint structures: It looks at your URL and thinks "hmm, this looks like it wants to be RESTful" or "this is clearly someone's first API, bless their heart."
• Generates curl commands for most probable API endpoints: No more manually typing out curl commands only to get 404s. It does the typing, you do the judging.
• Learns from 404 responses to refine future guesses: Each failure makes it smarter, unlike my attempts to learn guitar.
• Produces 'probable documentation' in markdown format: Documentation that's probably right is better than documentation that's definitely wrong.
• Includes confidence scores for each speculated endpoint: Know when it's 90% sure about /users versus when it's just throwing spaghetti at the wall with /api/thingamajigs.

Conclusion: Stop Guessing, Start Speculating

The API Speculation Engine won't write your integration code for you, but it will save you from the soul-crushing process of manually discovering endpoints through trial and error. It turns what used to be hours of frustration into minutes of automated speculation. The documentation it generates might even be good enough to share with your team—though I'd still call it "probable" rather than "definitive" in standup.

Try it out: https://github.com/BoopyCode/api-speculation-engine-1767533881

Remember: in a world where API documentation is often fiction, sometimes the best response is to write your own—with a little automated help. Now if only someone would build a tool that could speculate about why the API returns "success: false" when clearly everything worked perfectly.