| name | add-http-client |
| description | Add a new external HTTP client with config, endpoints, IO types, and an adapter. Use when integrating a new external API. |
| argument-hint | <service-name> |
Add an HTTP Client
Create a full external HTTP client integration following the project's layered pattern.
Arguments
$0 -- Service name (e.g., stripe, twilio, sendgrid)
Current Clients
!ls backend/infra/external/http/ 2>/dev/null
Implementation Steps
1. Create directory structure
backend/infra/external/http/{service}/
├── __init__.py
├── client.py
├── config.py
├── endpoints.py
└── io/
├── __init__.py
└── responses.py
2. Create config
File: backend/infra/external/http/{service}/config.py
from backend.internal.dto import StructDTO
class {Service}Config(StructDTO):
{SERVICE}_BASE_URL: str
{SERVICE}_API_KEY: str
3. Create endpoints
File: backend/infra/external/http/{service}/endpoints.py
from enum import StrEnum
class {Service}Endpoints(StrEnum):
SEND_MESSAGE = "/v1/messages"
GET_STATUS = "/v1/messages/{id}"
4. Create IO types
File: backend/infra/external/http/{service}/io/responses.py
from backend.internal.dto import StructDTO
class SendMessageResponse(StructDTO):
id: str
status: str
5. Create client
File: backend/infra/external/http/{service}/client.py
from backend.infra.external.http.client import HTTPClient
from backend.internal.result import Result
from .config import {Service}Config
from .endpoints import {Service}Endpoints
from .io.responses import SendMessageResponse
class {Service}Client(HTTPClient[{Service}Config]):
async def send_message(self, *, to: str, body: str) -> Result[SendMessageResponse, ...]:
response = await self._session.post(
{Service}Endpoints.SEND_MESSAGE,
json={"to": to, "body": body},
headers={"Authorization": f"Bearer {self._config.{SERVICE}_API_KEY}"},
)
return response.as_result(SendMessageResponse)
6. Create init.py
File: backend/infra/external/http/{service}/__init__.py
from .client import {Service}Client
from .config import {Service}Config
__all__ = ("{Service}Client", "{Service}Config")
7. Create adapter (if implementing a port)
File: backend/infra/external/adapters/{name}.py
from typing import final
from backend.app.shared.ports.{category}.{port} import {PortName}
from backend.infra.external.http.{service} import {Service}Client
@final
class Impl{Service}{PortName}({PortName}):
def __init__(self, client: {Service}Client) -> None:
self._client = client
async def send(self, *, to: str, message: str) -> None:
(await self._client.send_message(to=to, body=message)).raise_()
8. Wire in DI
File: backend/entry/rest/main/ioc.py
from backend.infra.external.http.sessions.aiohttp import AiohttpConfig, create_aiohttp_session
def _create_{service}_client(config: {Service}Config) -> {Service}Client:
session = create_aiohttp_session(AiohttpConfig(BASE_URL=config.{SERVICE}_BASE_URL))
return {Service}Client(session=session, config=config)
Add to an existing provider or create a new one. Bind adapter to port Protocol.
9. Verify
Run just check.
