Skip to content

External Service Port

external_service_port

External service port for abstract HTTP client operations.

Defines the ExternalServicePort 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.

ExternalServicePort

Bases: OutboundPort[RequestType, ResponseType], Protocol

Protocol for making HTTP requests to external services.

Any object with the async request, get, post, put,
and delete methods satisfies this protocol — no inheritance required.

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
Source code in src/forging_blocks/application/ports/outbound/external_service_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
class ExternalServicePort[RequestType, ResponseType](
    OutboundPort[RequestType, ResponseType],
    Protocol,
):
    """Protocol for making HTTP requests to external services.

    Any object with the async ``request``, ``get``, ``post``, ``put``,
    and ``delete`` methods satisfies this protocol — no inheritance required.

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

    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.
        """
        ...

    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.
        """
        ...

    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.
        """
        ...

    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.
        """
        ...

    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 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/external_service_port.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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 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/external_service_port.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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 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/external_service_port.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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 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/external_service_port.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
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 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/external_service_port.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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.
    """
    ...