Skip to content

Http Client Port

http_client_port

HTTP client port for abstract HTTP client operations.

Defines the HttpClientPort that application code depends on,
decoupling HTTP requests from any specific client implementation.

Responsibilities
  • Send HTTP requests (GET, POST, PUT, DELETE) to external services.
  • Abstract transport details (HTTP libraries, connection pooling).
Non-Responsibilities
  • Retry logic or circuit-breaking (handled by infrastructure/decorators).
  • Serialization or deserialization of request/response bodies.
  • Service discovery or URL resolution.

HttpClientPort

Bases: OutboundPort

ABC for making HTTP requests to external services.

Class Type Parameters:

Name Bound or Constraints Description Default
RequestType

The type of the request body.

 required
ResponseType

The type of the response body.

 required
Example 
client = MyHttpClient[dict[str, object], bytes]()
data = await client.get("https://api.example.com/orders/42")
result = await client.post("https://api.example.com/orders", body={"item": "widget"})
Source code in src/forging_blocks/application/ports/outbound/http_client_port.py 
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class HttpClientPort[RequestType, ResponseType](
    OutboundPort,
):
    """ABC for making HTTP requests to external services.

    Type Parameters:
        RequestType: The type of the request body.
        ResponseType: The type of the response body.

    Example:
        ```python
        client = MyHttpClient[dict[str, object], bytes]()
        data = await client.get("https://api.example.com/orders/42")
        result = await client.post("https://api.example.com/orders", body={"item": "widget"})
        ```
    """

    @abstractmethod
    async def request(
        self,
        method: str,
        url: str,
        headers: dict[str, str] | None = None,
        body: RequestType | None = None,
    ) -> ResponseType:
        """Send an HTTP request with the given method, URL, and optional body.

        Args:
            method: HTTP method (GET, POST, PUT, DELETE, etc.).
            url: The target URL.
            headers: Optional HTTP headers.
            body: Optional request body.

        Returns:
            The response body of type ResponseType.

        """
        ...

    @abstractmethod
    async def get(
        self,
        url: str,
        headers: dict[str, str] | None = None,
    ) -> ResponseType:
        """Send an HTTP GET request.

        Args:
            url: The target URL.
            headers: Optional HTTP headers.

        Returns:
            The response body of type ResponseType.

        """
        ...

    @abstractmethod
    async def post(
        self,
        url: str,
        body: RequestType | None = None,
        headers: dict[str, str] | None = None,
    ) -> ResponseType:
        """Send an HTTP POST request.

        Args:
            url: The target URL.
            body: The request body.
            headers: Optional HTTP headers.

        Returns:
            The response body of type ResponseType.

        """
        ...

    @abstractmethod
    async def put(
        self,
        url: str,
        body: RequestType | None = None,
        headers: dict[str, str] | None = None,
    ) -> ResponseType:
        """Send an HTTP PUT request.

        Args:
            url: The target URL.
            body: The request body.
            headers: Optional HTTP headers.

        Returns:
            The response body of type ResponseType.

        """
        ...

    @abstractmethod
    async def delete(
        self,
        url: str,
        headers: dict[str, str] | None = None,
    ) -> ResponseType:
        """Send an HTTP DELETE request.

        Args:
            url: The target URL.
            headers: Optional HTTP headers.

        Returns:
            The response body of type ResponseType.

        """
        ...

request(method: str, url: str, headers: dict[str, str] | None = None, body: RequestType | None = None) -> ResponseType abstractmethod async

Send an HTTP request with the given method, URL, and optional body.

Parameters:

Name Type Description Default
method str

HTTP method (GET, POST, PUT, DELETE, etc.).

 required
url str

The target URL.

 required
headers dict[str, str] | None

Optional HTTP headers.

 None
body RequestType | None

Optional request body.

 None

Returns:

Type Description
ResponseType

The response body of type ResponseType.
Source code in src/forging_blocks/application/ports/outbound/http_client_port.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@abstractmethod
async def request(
    self,
    method: str,
    url: str,
    headers: dict[str, str] | None = None,
    body: RequestType | None = None,
) -> ResponseType:
    """Send an HTTP request with the given method, URL, and optional body.

    Args:
        method: HTTP method (GET, POST, PUT, DELETE, etc.).
        url: The target URL.
        headers: Optional HTTP headers.
        body: Optional request body.

    Returns:
        The response body of type ResponseType.

    """
    ...

get(url: str, headers: dict[str, str] | None = None) -> ResponseType abstractmethod async

Send an HTTP GET request.

Parameters:

Name Type Description Default
url str

The target URL.

 required
headers dict[str, str] | None

Optional HTTP headers.

 None

Returns:

Type Description
ResponseType

The response body of type ResponseType.
Source code in src/forging_blocks/application/ports/outbound/http_client_port.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@abstractmethod
async def get(
    self,
    url: str,
    headers: dict[str, str] | None = None,
) -> ResponseType:
    """Send an HTTP GET request.

    Args:
        url: The target URL.
        headers: Optional HTTP headers.

    Returns:
        The response body of type ResponseType.

    """
    ...

post(url: str, body: RequestType | None = None, headers: dict[str, str] | None = None) -> ResponseType abstractmethod async

Send an HTTP POST request.

Parameters:

Name Type Description Default
url str

The target URL.

 required
body RequestType | None

The request body.

 None
headers dict[str, str] | None

Optional HTTP headers.

 None

Returns:

Type Description
ResponseType

The response body of type ResponseType.
Source code in src/forging_blocks/application/ports/outbound/http_client_port.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@abstractmethod
async def post(
    self,
    url: str,
    body: RequestType | None = None,
    headers: dict[str, str] | None = None,
) -> ResponseType:
    """Send an HTTP POST request.

    Args:
        url: The target URL.
        body: The request body.
        headers: Optional HTTP headers.

    Returns:
        The response body of type ResponseType.

    """
    ...

put(url: str, body: RequestType | None = None, headers: dict[str, str] | None = None) -> ResponseType abstractmethod async

Send an HTTP PUT request.

Parameters:

Name Type Description Default
url str

The target URL.

 required
body RequestType | None

The request body.

 None
headers dict[str, str] | None

Optional HTTP headers.

 None

Returns:

Type Description
ResponseType

The response body of type ResponseType.
Source code in src/forging_blocks/application/ports/outbound/http_client_port.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@abstractmethod
async def put(
    self,
    url: str,
    body: RequestType | None = None,
    headers: dict[str, str] | None = None,
) -> ResponseType:
    """Send an HTTP PUT request.

    Args:
        url: The target URL.
        body: The request body.
        headers: Optional HTTP headers.

    Returns:
        The response body of type ResponseType.

    """
    ...

delete(url: str, headers: dict[str, str] | None = None) -> ResponseType abstractmethod async

Send an HTTP DELETE request.

Parameters:

Name Type Description Default
url str

The target URL.

 required
headers dict[str, str] | None

Optional HTTP headers.

 None

Returns:

Type Description
ResponseType

The response body of type ResponseType.
Source code in src/forging_blocks/application/ports/outbound/http_client_port.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
@abstractmethod
async def delete(
    self,
    url: str,
    headers: dict[str, str] | None = None,
) -> ResponseType:
    """Send an HTTP DELETE request.

    Args:
        url: The target URL.
        headers: Optional HTTP headers.

    Returns:
        The response body of type ResponseType.

    """
    ...