# APIGen

Turn any API into Python code. No docs needed.

> [!WARNING]
> Experimental software. Review generated code before production use.

```python
# Generate from any API
$ apigen generate https://api.github.com

# Use it immediately
>>> from generated_tools.api_github_com import ApiGithubCom
>>> client = ApiGithubCom(api_key="ghp_...")
>>> user = client.list_user()
>>> print(user['login'])
'your-username'
```

## What it does

Point APIGen at any API URL. Get working Python code with methods, auth, and type hints.

Works with:

- APIs that have OpenAPI specs
- APIs that don't have any docs
- Public and authenticated APIs

## Install

```bash
pip install apigen-ai
```

## Quick start

```bash
# Public API
apigen generate https://jsonplaceholder.typicode.com

# Authenticated API
apigen generate https://api.github.com
```

Generated code goes in `generated_tools/`.

## Example: GitHub API

```bash
apigen generate https://api.github.com
```

Creates `generated_tools/api.github.com.py` with:

```python
class ApiGithubCom:
    def __init__(self, api_key=None):
        self.base_url = "https://api.github.com"
        self.api_key = api_key

    def list_user(self) -> Dict:
        """Get authenticated user"""
        ...

    def list_users(self, page=None, limit=None) -> Dict:
        """List all users"""
        ...

    def get_users(self, id) -> Dict:
        """Get specific user"""
        ...
```

Use it:

```python
import importlib.util

spec = importlib.util.spec_from_file_location(
    "api", "generated_tools/api.github.com.py"
)
api = importlib.util.module_from_spec(spec)
spec.loader.exec_module(api)

client = api.ApiGithubCom(api_key="ghp_your_token")
user = client.list_user()
print(f"Logged in as: {user['login']}")
```

## How it works

**Phase 1: Check for OpenAPI spec**

- Probes `/openapi.json`, `/swagger.json`, etc.
- Parses endpoints, parameters, auth
- Generates full method signatures

**Phase 2: Probe the API**

- Tests common patterns (`/users`, `/api/v1`, `/products`)
- Detects auth from response headers
- Infers parameters from responses
- Discovers ID-based endpoints

**Result:** Clean Python code that works.

## Commands

```bash
# Generate tool
apigen generate <url>

# Skip Elasticsearch (faster)
apigen generate <url> --skip-index

# Search catalog (requires Elasticsearch)
apigen search "payment apis"

# Setup Elasticsearch
apigen setup
```

## Configuration

Optional `.env` file:

```bash
ELASTICSEARCH_HOST=localhost
ELASTICSEARCH_PORT=9200
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASSWORD=changeme
```

## Requirements

- Python 3.11+
- Elasticsearch 8.15+ (optional, for search)
- Docker (optional, for Elasticsearch)

## What gets generated

Every tool includes:

- Method signatures with parameters
- Authentication (Bearer, API key, OAuth)
- Type hints
- Docstrings
- Error handling
- Query parameter support

## Limitations

- Review generated code before production
- Complex auth may need manual tweaks
- No rate limiting
- No WebSocket/GraphQL support yet

## Contributing

Issues and PRs welcome.

Areas for improvement:

- More auth methods
- Better parameter inference
- GraphQL support
- WebSocket support

## License

MIT
