api-client

Integrating an external HTTP API

An external API integration is two objects, not one:

1. Client (infrastructure/http/clients/<vendor>/) — thin HTTP wrapper. Returns raw vendor-shaped Pydantic models that mirror the API's JSON 1:1. No business logic, no transformation, no domain types.
2. Service (application/v1/services/<vendor>.py) — holds a Client via its port, calls it, and maps raw responses into application Result types. All business rules (enum mapping, filtering, multi-call orchestration) live here. The service never returns Create*Type / Update*Type — persistence shape is the use case's job.

Use cases depend on the Service. In rare cases (debug/proxy/admin) they can depend on the Client port directly. Examples below use a Stripe-shaped payment provider — substitute your vendor.

Layer split

The project's rule (CLAUDE.md): application/ cannot import from infrastructure/; infrastructure/ can import from application/. Every type application-code reads must live in application/.

src/
├── application/
│   ├── common/interfaces/<vendor>/
│   │   ├── port.py              ← Protocol <Vendor>Client
│   │   ├── types.py             ← VENDOR enums/literals
│   │   └── responses.py         ← raw Pydantic DTOs (1:1 with API JSON)
│   ├── v1/results/<entity>.py   ← application Result (PaymentResult, …)
│   └── v1/services/<vendor>.py  ← <Vendor>Service: raw → Result
│
└── infrastructure/http/clients/<vendor>/
    ├── client.py                ← <Vendor>API(Client) — implements port structurally
    └── endpoints.py              ← StrEnum of URL paths

Raw response DTOs and vendor enums live in application/ because the service in application reads them. They become part of the port contract — the same pattern as JWT/TokenType, Cache/CacheKey: the port owns its vocabulary.

The Client — raw and dumb

Jobs: know the vendor's URL/auth, send HTTP, parse JSON into application-defined DTOs, translate HTTP errors into application exceptions. Never contains business branching or domain types.