Api Docs

Phase 2: Extract Core Information

For each endpoint you need to integrate, extract:

ENDPOINT ANALYSIS
================
Name: [endpoint name]
URL: [full URL with base + path]
Method: [GET/POST/PUT/DELETE/PATCH]
Authentication: [type and header format]

REQUEST FORMAT:
- Headers: [required headers]
- Query params: [parameters with types]
- Body: [JSON schema or example]

RESPONSE FORMAT:
- Success (2xx): [JSON schema or example]
- Errors: [error codes and meanings]

RATE LIMITS:
- Requests per minute/hour: [limit]
- Retry strategy: [when to retry]

Phase 3: Authentication Analysis

Document the authentication method completely:

AUTHENTICATION
==============
Type: [API Key / Bearer Token / OAuth2 / Basic]
Header Name: [e.g., "Authorization"]
Header Value Format: [e.g., "Bearer {api_key}"]
Where to get key: [URL or instructions]
Key rotation: [if applicable]

Phase 4: Error Handling

List all possible errors:

ERROR CODES
===========
400 - Bad Request: [common causes]
401 - Unauthorized: [fix instructions]
403 - Forbidden: [permissions needed]
404 - Not Found: [what this means]
429 - Rate Limited: [retry after]
500 - Server Error: [what to do]

Phase 5: Generate Working Code

Create a working integration example:

# Example structure
import httpx  # or requests

class APIClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.example.com/v1"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    async def endpoint_name(self, param1: str) -> dict:
        """
        [Description from docs]

        Args:
            param1: [description]

        Returns:
            [response description]

        Raises:
            HTTPError: [when]
        """
        response = await self.client.post(
            f"{self.base_url}/endpoint",
            headers=self.headers,
            json={"param1": param1}
        )
        response.raise_for_status()
        return response.json()

Phase 6: Test the Integration

1. Create a minimal test script
2. Test with real credentials (ask user for API key if needed)
3. Verify the response matches documentation
4. Document any discrepancies

Output Format

After analysis, provide a structured report:

# API Integration Report: [API Name]

## Quick Reference

| Item | Value |
|------|-------|
| Base URL | `https://api.example.com/v1` |
| Auth Type | Bearer Token |
| Auth Header | `Authorization: Bearer {key}` |
| Rate Limit | 100 req/min |
| Docs URL | [link] |

## Endpoints Needed

### 1. [Endpoint Name]
- **URL:** `POST /endpoint`
- **Purpose:** [description]
- **Request:** [example]
- **Response:** [example]

## Working Code

[Complete, tested code example]

## Common Issues

1. [Issue 1]: [Solution]
2. [Issue 2]: [Solution]

## Environment Variables

```env
API_NAME_KEY=your_api_key_here
API_NAME_BASE_URL=https://api.example.com/v1

## Key Principles

- **Fetch, don't assume** - Always read the actual documentation
- **Test immediately** - Verify with a real API call before claiming understanding
- **Document discrepancies** - Real APIs often differ from their docs
- **Handle errors gracefully** - Always implement proper error handling
- **Respect rate limits** - Implement backoff and retry logic

## Tools to Use

- `WebFetch` - To read documentation pages
- `WebSearch` - To find additional examples or troubleshooting
- `Bash` with `curl` - To test API endpoints directly
- `Write` - To generate integration code