import requests
import re
from typing import List, Optional

def find_working_endpoint(base_url: str, endpoint_path: str) -> Optional[str]:
    """
    Try common API version patterns to find a working endpoint.
    Returns the first successful URL or None if all fail.
    """
    
    # Common version patterns found in the wild
    version_patterns = [
        '/v1', '/v2', '/v3', '/v4',
        '/v1.0', '/v2.0', '/v3.0',
        '/api/v1', '/api/v2', '/api/v3',
        '/v1.5', '/v2.1', '/v3-beta',
        '/latest', '/stable', '/current',
        ''  # Try without version (sometimes works!)
    ]
    
    for version in version_patterns:
        test_url = f"{base_url.rstrip('/')}{version}/{endpoint_path.lstrip('/')}"
        
        try:
            response = requests.get(test_url, timeout=5)
            
            # Check for successful response (2xx status)
            if 200 <= response.status_code < 300:
                # Verify it returns JSON (common API expectation)
                if 'application/json' in response.headers.get('Content-Type', ''):
                    return test_url
                
        except requests.RequestException:
            continue  # Try next pattern
    
    return None  # No working endpoint found


# Example usage:
# working_endpoint = find_working_endpoint(
#     base_url="https://api.example.com",
#     endpoint_path="users"
# )
# print(f"Working endpoint: {working_endpoint}")

The Problem: API Versioning as a Form of Psychological Warfare

Let's be honest: API versioning is where good engineering principles go to die. It starts innocently enough with a /v1/users endpoint. Then someone decides we need /v2/users but forgets to tell anyone. Meanwhile, /v1.5/users appears mysteriously in the staging environment, documented only in a Slack thread from 2019 that's since been deleted. The 'latest' version in the official docs returns a 410 GONE status, which is ironically accurate because the developer who wrote it has since left the company.

This isn't just annoying—it's a productivity black hole. You'll waste hours trying endpoints like an archaeologist deciphering hieroglyphics. /api/v3-beta/users? 404. /api/v2.1/users? Returns data in XML when you expected JSON. /api/users (no version)? Congratulations, you've reached the internal testing endpoint that exposes everyone's passwords. Who needs proper documentation when you can have this delightful guessing game?

The worst part? The people who build these APIs genuinely believe their versioning strategy makes sense. They'll give talks at conferences about 'semantic versioning for REST APIs' while their production environment runs seven different incompatible versions, each maintained by a different team that hasn't spoken to each other since the company holiday party where someone ate all the shrimp.

The Solution: When All Else Fails, Ask the Spirits

I built API Versioning Ouija Board because I got tired of sacrificing my lunch break to the API gods. This tool doesn't pretend to have all the answers—it just makes educated guesses based on what the API actually returns. Think of it as a debugging medium: it contacts the spiritual realm of server responses to ask, "Hey, which version should this poor developer use?"

Here's how it works: you give it a base URL and some endpoint patterns, and it systematically probes different version configurations. It analyzes response codes, headers, and even response times to determine which version is most likely the 'active' one. Does it return a 200 OK? Good sign. Does it return data that looks like actual JSON and not an error message in Portuguese? Even better. Does it respond faster than the deprecated versions? Jackpot.

The magic happens in the pattern analysis. The tool looks for clues like version headers (X-API-Version), semantic versioning in response bodies, and even the presence of deprecation warnings. It weights these signals to calculate a 'confidence score' for each version. The higher the score, the more likely that version is what you should be using. It's not perfect, but it's better than flipping a coin or reading documentation that was last updated during the Obama administration.

And yes, the 'spiritual guidance' messages are intentionally ridiculous. When it suggests version 2.1 with 85% confidence, it might say something like, "The spirits sense much activity on this path. Many requests have traveled here recently." It's a reminder that we're all just guessing anyway, so we might as well have fun with it.

How to Use It: Channeling Your Inner API Medium

Getting started is easier than convincing your product manager that proper API documentation is worth the effort. Install it via pip:

pip install api-versioning-ouija-board

Basic usage looks like this—here's a snippet from the main module showing the core functionality:

from ouija_board import APIVersionDetector

# Initialize with your base URL
detector = APIVersionDetector(base_url="https://api.example.com")

# Add endpoint patterns to check
detector.add_endpoint_pattern("/users")
detector.add_endpoint_pattern("/posts/{id}")

# Let the spirits guide you
results = detector.detect_versions()

# Get the recommendation
recommendation = detector.get_recommendation()
print(f"The spirits suggest: {recommendation['version']}")
print(f"Confidence: {recommendation['confidence']}%")
print(f"Guidance: {recommendation['message']}")

Check out the full source code on GitHub for more advanced features like custom header analysis, response time thresholds, and the ability to ignore certain version patterns (because we all know /v0.1-alpha-experimental is just someone's Friday side project that somehow made it to production).

The tool outputs a detailed analysis showing which versions returned what status codes, how long they took to respond, and what clues were found in the responses. It's like getting a forensic report on your API's versioning chaos, complete with sarcastic commentary about the state of modern web development.

Key Features: What the Spirits Can Do For You

• Analyzes API responses for version clues: Looks for version headers, deprecation warnings, and semantic versioning in response bodies
• Suggests most likely active version based on response patterns: Uses weighted scoring of response codes, headers, and performance
• Generates 'spiritual guidance' messages with version recommendations: Because regular error messages are boring
• Configurable endpoint patterns and version formats: Supports everything from /v1 to /api/v2023-Q2-beta
• Parallel probing for faster results: Because your time is valuable, even if the API documentation isn't
• Export results to JSON: For when you need to prove to your team that yes, the versioning really is this bad

Conclusion: Embrace the Chaos (But With Better Tools)

The API Versioning Ouija Board won't fix bad API design or magically create documentation where none exists. What it will do is save you hours of manual testing and frustration by systematically probing endpoints and giving you data-driven suggestions. It turns the art of guessing into something resembling science, or at least organized guesswork with pretty output.

In a perfect world, every API would have clear, up-to-date documentation with proper versioning strategies. But we don't live in that world. We live in a world where /v2 is deprecated, /v3 is in beta, /v2.1 is the 'stable' version but only on Tuesdays, and the documentation links to a Confluence page that requires VPN access from a specific office in a different time zone. Until that changes, we need tools like this.

Try it out: https://github.com/BoopyCode/api-versioning-ouija-board

May the spirits of deprecated endpoints guide you to working code, and may your next API integration involve less guesswork and more actual development. Or at least, better entertainment while you're guessing.