HTTP API

The HTTP API provides utilities for making HTTP requests and handling HTTP-related functionality.

Core Components

HTTPClient

get async

get(_resp: type[T] | T = dict, *, url: str, options: HTTPOptions | None = None) -> T

Send a GET request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

post async

post(_resp: type[T] | T = dict, *, url: str, content: Any | BaseModel | None, options: HTTPOptions | None = None) -> T

Send a POST request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models).	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

put async

put(_resp: type[T] | T = dict, *, url: str, content: Any | BaseModel | None, options: HTTPOptions | None = None) -> T

Send a PUT request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models).	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

patch async

patch(_resp: type[T] | T = dict, *, url: str, content: Any | BaseModel | None, options: HTTPOptions | None = None) -> T

Send a PATCH request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models).	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

delete async

delete(_resp: type[T] | T = dict, *, url: str, options: HTTPOptions | None = None) -> T

Send a DELETE request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

stream

stream(_resp: type[T] | T = dict, *, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], url: str, content: Any | BaseModel | None = None, options: HTTPOptions | None = None) -> Observable[T]

Send a streaming request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
method	Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']	The HTTP method to use for the request.	required
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models). Defaults to None.	None
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Type	Description
Observable[T]	Observable[T]: An observable that emits the response from the server.

Raises:

Type	Description
HTTPError	If an error occurs during the HTTP request.

HTTPOptions

Bases: TypedDict

Source code in ascender/common/http/types/http_options.py

class HTTPOptions(TypedDict):
    params: NotRequired[QueryParamTypes]
    headers: NotRequired[HeaderTypes]
    cookies: NotRequired[CookieTypes]
    auth: NotRequired[AuthTypes]
    follow_redirects: NotRequired[bool]
    timeout: NotRequired[TimeoutTypes]

provideHTTPClient

provideHTTPClient(base_url: str = '', interceptors: list[InterceptorFn | type[Interceptor]] = [], verify: SSLContext | str | bool = True, cert: CertTypes | None = None, trust_env: bool = True, client_instance: type[HTTPClient] = HTTPClient, **additional_configs) -> Provider

Provide a configured HTTPClient instance.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL for the HTTP client. Defaults to "".	''
interceptors	list[InterceptorFn | type[Interceptor]]	A list of interceptor functions or classes to use with the HTTP client. Defaults to [].	[]
verify	SSLContext | str | bool	Whether to verify SSL certificates. Defaults to True.	True
cert	CertTypes | None	The SSL certificate to use. Defaults to None.	None
trust_env	bool	Whether to trust the system's CA certificates. Defaults to True.	True
client_instance	type[HTTPClient]	The HTTP client class to use. Defaults to HTTPClient.	HTTPClient
**additional_configs		Additional keyword arguments forwarded to the HTTP client constructor.	{}

Returns:

Name	Type	Description
Provider	Provider	A provider for the HTTP client instance.

Interceptor

Bases: ABC

handle_request abstractmethod async

handle_request(request: InterceptorIn) -> Request

handle_response async

handle_response(response: Response)

InterceptorFn module-attribute

InterceptorFn = Awaitable[Callable[[Request], Request]]

See Also

• HTTP Client Guide - Comprehensive HTTP client guide
• Controllers - Controller request/response handling
• HTTPX Documentation - Underlying HTTP library (for http exception handling and advanced usage)