Connector Dev

connectors/{system}/
+-- AGENTS.md           # How to work with this connector
+-- SKILL.md            # What methods are available
+-- __init__.py         # Clean public API
+-- config.py           # Typed settings (BaseSettings)
+-- client.py           # HTTP client, auth, rate limiting
+-- gateway.py          # High-level facade (optional)
+-- services/
|   +-- base.py         # Shared patterns (pagination, error handling)
|   +-- {entity}.py     # One file per API entity (< 300 lines)
+-- openapi/            # Downloaded API specs

The 4-Tier Pattern

Lite Connector Structure (connector/lite)

connectors/{system}/
+-- client.py           # Everything in one file
+-- config.py           # Settings

Use when the API has few endpoints and simple auth.

Choosing Full vs Lite

Common Patterns

Base Service

class BaseService:
    def __init__(self, client: HttpClient) -> None:
        self._client = client

    def _paginate(
        self,
        endpoint: str,
        params: dict[str, str],
    ) -> Iterator[dict]:
        """Generic pagination handler."""
        next_token: str | None = None
        while True:
            if next_token:
                params["nextToken"] = next_token
            response = self._client.get(endpoint, params=params)
            yield from response["data"]
            next_token = response.get("nextToken")
            if not next_token:
                break

Settings

from pydantic_settings import BaseSettings, SettingsConfigDict

class AmazonSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="AMAZON_")

    client_id: str
    client_secret: str
    refresh_token: str
    marketplace_id: str = "A1F83G8C2ARO7P"

Checklist

• Read API docs before writing code
• Settings use BaseSettings (not hardcoded)
• Auth handled in client layer (not in services)
• Rate limiting respected
• Error responses handled gracefully
• AGENTS.md and SKILL.md created/updated

Scaffolding Procedure — New Connector

When creating a new connector from scratch, follow this sequence:

Step 1 — Requirements Gathering

Before writing any code:

1. Get the API documentation URL
2. Determine auth method (API key, OAuth2, token refresh)
3. List the entities/resources you need (orders, products, etc.)
4. Identify rate limits and pagination approach
5. Check if an OpenAPI spec is available (download to openapi/)

Step 2 — Choose Full vs Lite

Use the decision table above. Default to lite — you can always upgrade later.

Step 3 — Create Files (Full Connector)

Create files in this order — each builds on the previous:

Step 4 — Registration

After the connector is functional:

1. Add environment variables to .env.example
2. Add connector to project's AGENTS.md key files table
3. If using a connector registry, register the new connector
4. Update project README if it lists available integrations

Step 5 — Verification

• All endpoints return expected data with real credentials
• Rate limiting is respected (check response headers)
• Auth token refresh works (if applicable)
• Error responses are handled (not just happy path)
• Pagination works for endpoints that return lists

Anti-Patterns

See Also

• api-design — REST API design patterns (for the APIs you consume)
• security-review — Security considerations for API integrations
• dependency-management — Managing API client libraries