ds_protocol_http_py_lib.linked_service¶

File: __init__.py Region: ds_protocol_http_py_lib/linked_service

HTTP Linked Service

This module implements a linked service for HTTP APIs.

Example

>>> from ds_protocol_http_py_lib.enums import AuthType
>>> linked_service = HttpLinkedService(
...     id=uuid.uuid4(),
...     name="example::linked_service",
...     version="1.0.0",
...     settings=HttpLinkedServiceSettings(
...         host="api.example.com",
...         auth_type=AuthType.OAUTH2,
...         oauth2=OAuth2AuthSettings(
...             token_endpoint="https://auth.example.com/token",
...             client_id="my-client",
...             client_secret="secret",
...         ),
...     ),
... )
>>> linked_service.connect()

Submodules¶

ds_protocol_http_py_lib.linked_service.http

Classes¶

`ApiKeyAuthSettings`	Settings for API Key authentication.
`BasicAuthSettings`	Settings for HTTP Basic authentication.
`BearerAuthSettings`	Settings for Bearer token authentication.
`CustomAuthSettings`	Settings for custom token-based authentication.
`HttpLinkedService`	The class is used to connect with HTTP API.
`HttpLinkedServiceSettings`	Settings for HTTP linked service connections.
`OAuth2AuthSettings`	Settings for OAuth2 client credentials authentication.

Package Contents¶

class ds_protocol_http_py_lib.linked_service.ApiKeyAuthSettings[source]¶

Settings for API Key authentication.

The API key will be added as a header to all requests.

name: str¶: The header name for the API key (e.g., ‘X-API-Key’, ‘Authorization’).

value: str¶: The API key value. Masked in logs.

class ds_protocol_http_py_lib.linked_service.BasicAuthSettings[source]¶

Settings for HTTP Basic authentication.

Uses standard HTTP Basic auth with base64-encoded username:password.

username: str¶: The username for basic auth.

password: str¶: The password for basic auth.

class ds_protocol_http_py_lib.linked_service.BearerAuthSettings[source]¶

Settings for Bearer token authentication.

Fetches a token by posting username/password to a token endpoint, then uses the returned token as a Bearer token for subsequent requests.

token_endpoint: str¶: The URL to fetch the bearer token from.

username: str¶: The username value to send in the token request.

password: str¶: The password value to send in the token request.

username_key_name: str = 'email'¶: The JSON key name for username in the token request body.

password_key_name: str = 'password'¶: The JSON key name for password in the token request body.

class ds_protocol_http_py_lib.linked_service.CustomAuthSettings[source]¶

Settings for custom token-based authentication.

Posts to a token endpoint and extracts the access token from the response. Uses the common headers field from HttpLinkedServiceSettings for the token request.

token_endpoint: str¶: The URL to fetch the token from.

data: dict[str, str] | None = None¶: Custom JSON data to send with the token request.

class ds_protocol_http_py_lib.linked_service.HttpLinkedService[source]¶

Bases: ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService[HttpLinkedServiceSettingsType], Generic[HttpLinkedServiceSettingsType]

The class is used to connect with HTTP API.

settings: HttpLinkedServiceSettingsType¶

_session: ds_protocol_http_py_lib.utils.http.provider.Http | None = None¶

_http: ds_protocol_http_py_lib.utils.http.provider.Http | None = None¶

__post_init__() → None[source]¶

property type: ds_protocol_http_py_lib.enums.ResourceType¶: Get the type of the linked service. :returns: ResourceType

property connection: ds_protocol_http_py_lib.utils.http.provider.Http¶: Get the session. :returns: The session. :rtype: Http

_init_http() → ds_protocol_http_py_lib.utils.http.provider.Http[source]¶

Initialize the Http client instance with HttpConfig and TokenBucket.

Creates an Http instance with: - HttpConfig using headers from the linked service settings - TokenBucket with rate limiting (10 requests per second, capacity of 20)

Subclasses can override this method to customize the entire Http initialization, including custom HttpConfig, TokenBucket, or other Http parameters.

Returns:: The initialized Http client instance.
Return type:: Http

_fetch_user_token(http: ds_protocol_http_py_lib.utils.http.provider.Http) → str[source]¶

Fetch a user token from the token endpoint using the Http provider.

Parameters:

http – The Http instance to use for the request.

Returns:

The user token.

Return type:

str

Raises:

LinkedServiceException – If bearer settings are missing.
AuthenticationError – If the token is missing in the response.

_fetch_oauth2_token(http: ds_protocol_http_py_lib.utils.http.provider.Http) → str[source]¶

Fetch an OAuth2 token from the token endpoint using the Http provider.

Parameters:

http – The Http instance to use for the request.

Returns:

The OAuth2 token.

Return type:

str

Raises:

LinkedServiceException – If OAuth2 settings are missing.
AuthenticationError – If the token is missing in the response.

_configure_bearer_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) → None[source]¶

Configure Bearer authentication.

Fetches a user token via _fetch_user_token and sets the session’s Authorization header.

Parameters:: http – The Http client instance to configure.

_configure_oauth2_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) → None[source]¶

Configure OAuth2 (client credentials) authentication.

Fetches an OAuth2 token via _fetch_oauth2_token and sets the session’s Authorization header.

Parameters:: http – The Http client instance to configure.

_configure_basic_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) → None[source]¶

Configure HTTP Basic authentication.

Uses the basic auth settings to construct a base64-encoded username:password token and sets the session’s Authorization header.

Parameters:: http – The Http client instance to configure.
Raises:: LinkedServiceException – If basic auth settings are missing.

_configure_apikey_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) → None[source]¶

Configure API key authentication.

Updates the session headers with the configured API key name/value.

Parameters:: http – The Http client instance to configure.
Raises:: LinkedServiceException – If API key settings are missing.

_configure_custom_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) → None[source]¶

Configure custom authentication.

Calls the configured token endpoint and extracts an access token from the JSON response using common token key names. The resulting token is stored in the session Authorization header.

Parameters:

http – The Http client instance to configure.

Raises:

AuthenticationError – If the token is missing in the response.
LinkedServiceException – If custom auth settings are missing.

_configure_noauth(_http: ds_protocol_http_py_lib.utils.http.provider.Http) → None[source]¶

Configure no authentication.

This is a no-op handler used to keep the auth dispatch table fully typed.

Parameters:: _http – The Http client instance to configure.

connect() → None[source]¶

Connect to the HTTP API and configure authentication.

Initializes the Http client instance if not already initialized. Configures authentication based on the auth_type. Merges configured headers into the session, then applies auth configuration.

Header precedence: - settings.headers are applied first - the selected auth handler may override headers (especially Authorization)

Returns:

The session is configured.

Return type:

None

Raises:

AuthenticationError – If the authentication fails.
LinkedServiceException – If the auth_type is unsupported.

test_connection() → tuple[bool, str][source]¶

Test the connection to the HTTP API.

Returns:: A tuple containing a boolean indicating success and a string message.
Return type:: tuple[bool, str]

close() → None[source]¶: Close the linked service.

class ds_protocol_http_py_lib.linked_service.HttpLinkedServiceSettings[source]¶

Bases: ds_resource_plugin_py_lib.common.resource.linked_service.LinkedServiceSettings

Settings for HTTP linked service connections.

Provide the appropriate auth settings object based on your auth_type:

AuthType.API_KEY → api_key
AuthType.BASIC → basic
AuthType.BEARER → bearer
AuthType.OAUTH2 → oauth2
AuthType.CUSTOM → custom
AuthType.NO_AUTH → (no auth settings needed)

Example

>>> settings = HttpLinkedServiceSettings(
...     host="api.example.com",
...     auth_type=AuthType.OAUTH2,
...     oauth2=OAuth2AuthSettings(
...         token_endpoint="https://auth.example.com/token",
...         client_id="my-client",
...         client_secret="secret",
...     ),
... )

host: str¶: The API host (e.g., ‘api.example.com’).

auth_type: ds_protocol_http_py_lib.enums.AuthType¶: The authentication type to use.

schema: str = 'https'¶: URL scheme (‘http’ or ‘https’).

port: int | None = None¶: Optional port number.

headers: dict[str, str] | None = None¶: Additional headers to include with all requests.

api_key: ApiKeyAuthSettings | None = None¶: Settings for API Key authentication. Required when auth_type=AuthType.API_KEY.

basic: BasicAuthSettings | None = None¶: Settings for Basic authentication. Required when auth_type=AuthType.BASIC.

bearer: BearerAuthSettings | None = None¶: Settings for Bearer token authentication. Required when auth_type=AuthType.BEARER.

oauth2: OAuth2AuthSettings | None = None¶: Settings for OAuth2 client credentials authentication. Required when auth_type=AuthType.OAUTH2.

custom: CustomAuthSettings | None = None¶: Settings for custom token authentication. Required when auth_type=AuthType.CUSTOM.

class ds_protocol_http_py_lib.linked_service.OAuth2AuthSettings[source]¶

Settings for OAuth2 client credentials authentication.

Uses the OAuth2 client credentials flow to obtain an access token.

token_endpoint: str¶: The OAuth2 token endpoint URL.

client_id: str¶: The OAuth2 client ID.

client_secret: str¶: The OAuth2 client secret.

scope: str | None = None¶: Optional OAuth2 scope(s).