ds_protocol_http_py_lib.linked_service.http =========================================== .. py:module:: ds_protocol_http_py_lib.linked_service.http .. autoapi-nested-parse:: **File:** ``http.py`` **Region:** ``ds_protocol_http_py_lib/linked_service/http`` HTTP Linked Service This module implements a linked service for HTTP APIs. .. rubric:: Example >>> from ds_protocol_http_py_lib import HttpLinkedService, HttpLinkedServiceSettings >>> from ds_protocol_http_py_lib.linked_service import OAuth2AuthSettings >>> from ds_protocol_http_py_lib.enums import AuthType >>> linked_service = HttpLinkedService( ... 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() Attributes ---------- .. autoapisummary:: ds_protocol_http_py_lib.linked_service.http.HttpLinkedServiceSettingsType Classes ------- .. autoapisummary:: ds_protocol_http_py_lib.linked_service.http.ApiKeyAuthSettings ds_protocol_http_py_lib.linked_service.http.BasicAuthSettings ds_protocol_http_py_lib.linked_service.http.BearerAuthSettings ds_protocol_http_py_lib.linked_service.http.OAuth2AuthSettings ds_protocol_http_py_lib.linked_service.http.CustomAuthSettings ds_protocol_http_py_lib.linked_service.http.HttpLinkedServiceSettings ds_protocol_http_py_lib.linked_service.http.HttpLinkedService Module Contents --------------- .. py:class:: ApiKeyAuthSettings Settings for API Key authentication. The API key will be added as a header to all requests. .. py:attribute:: name :type: str The header name for the API key (e.g., 'X-API-Key', 'Authorization'). .. py:attribute:: value :type: str The API key value. Masked in logs. .. py:class:: BasicAuthSettings Settings for HTTP Basic authentication. Uses standard HTTP Basic auth with base64-encoded username:password. .. py:attribute:: username :type: str The username for basic auth. .. py:attribute:: password :type: str The password for basic auth. .. py:class:: BearerAuthSettings 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. .. py:attribute:: token_endpoint :type: str The URL to fetch the bearer token from. .. py:attribute:: username :type: str The username value to send in the token request. .. py:attribute:: password :type: str The password value to send in the token request. .. py:attribute:: username_key_name :type: str :value: 'email' The JSON key name for username in the token request body. .. py:attribute:: password_key_name :type: str :value: 'password' The JSON key name for password in the token request body. .. py:class:: OAuth2AuthSettings Settings for OAuth2 client credentials authentication. Uses the OAuth2 client credentials flow to obtain an access token. .. py:attribute:: token_endpoint :type: str The OAuth2 token endpoint URL. .. py:attribute:: client_id :type: str The OAuth2 client ID. .. py:attribute:: client_secret :type: str The OAuth2 client secret. .. py:attribute:: scope :type: str | None :value: None Optional OAuth2 scope(s). .. py:class:: CustomAuthSettings 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. .. py:attribute:: token_endpoint :type: str The URL to fetch the token from. .. py:attribute:: data :type: dict[str, str] | None :value: None Custom JSON data to send with the token request. .. py:class:: HttpLinkedServiceSettings Bases: :py:obj:`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) .. rubric:: 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", ... ), ... ) .. py:attribute:: host :type: str The API host (e.g., 'api.example.com'). .. py:attribute:: auth_type :type: ds_protocol_http_py_lib.enums.AuthType The authentication type to use. .. py:attribute:: schema :type: str :value: 'https' URL scheme ('http' or 'https'). .. py:attribute:: port :type: int | None :value: None Optional port number. .. py:attribute:: headers :type: dict[str, str] | None :value: None Additional headers to include with all requests. .. py:attribute:: api_key :type: ApiKeyAuthSettings | None :value: None Settings for API Key authentication. Required when auth_type=AuthType.API_KEY. .. py:attribute:: basic :type: BasicAuthSettings | None :value: None Settings for Basic authentication. Required when auth_type=AuthType.BASIC. .. py:attribute:: bearer :type: BearerAuthSettings | None :value: None Settings for Bearer token authentication. Required when auth_type=AuthType.BEARER. .. py:attribute:: oauth2 :type: OAuth2AuthSettings | None :value: None Settings for OAuth2 client credentials authentication. Required when auth_type=AuthType.OAUTH2. .. py:attribute:: custom :type: CustomAuthSettings | None :value: None Settings for custom token authentication. Required when auth_type=AuthType.CUSTOM. .. py:data:: HttpLinkedServiceSettingsType .. py:class:: HttpLinkedService Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService`\ [\ :py:obj:`HttpLinkedServiceSettingsType`\ ], :py:obj:`Generic`\ [\ :py:obj:`HttpLinkedServiceSettingsType`\ ] The class is used to connect with HTTP API. .. py:attribute:: settings :type: HttpLinkedServiceSettingsType .. py:attribute:: _session :type: ds_protocol_http_py_lib.utils.http.provider.Http | None :value: None .. py:attribute:: _http :type: ds_protocol_http_py_lib.utils.http.provider.Http | None :value: None .. py:method:: __post_init__() -> None .. py:property:: type :type: ds_protocol_http_py_lib.enums.ResourceType Get the type of the linked service. :returns: ResourceType .. py:property:: connection :type: ds_protocol_http_py_lib.utils.http.provider.Http Get the session. :returns: The session. :rtype: Http .. py:method:: _init_http() -> ds_protocol_http_py_lib.utils.http.provider.Http 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. :rtype: Http .. py:method:: _fetch_user_token(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> str Fetch a user token from the token endpoint using the Http provider. :param http: The Http instance to use for the request. :returns: The user token. :rtype: str :raises LinkedServiceException: If bearer settings are missing. :raises AuthenticationError: If the token is missing in the response. .. py:method:: _fetch_oauth2_token(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> str Fetch an OAuth2 token from the token endpoint using the Http provider. :param http: The Http instance to use for the request. :returns: The OAuth2 token. :rtype: str :raises LinkedServiceException: If OAuth2 settings are missing. :raises AuthenticationError: If the token is missing in the response. .. py:method:: _configure_bearer_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> None Configure Bearer authentication. Fetches a user token via `_fetch_user_token` and sets the session's Authorization header. :param http: The Http client instance to configure. .. py:method:: _configure_oauth2_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> None Configure OAuth2 (client credentials) authentication. Fetches an OAuth2 token via `_fetch_oauth2_token` and sets the session's Authorization header. :param http: The Http client instance to configure. .. py:method:: _configure_basic_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> None Configure HTTP Basic authentication. Uses the basic auth settings to construct a base64-encoded `username:password` token and sets the session's Authorization header. :param http: The Http client instance to configure. :raises LinkedServiceException: If basic auth settings are missing. .. py:method:: _configure_apikey_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> None Configure API key authentication. Updates the session headers with the configured API key name/value. :param http: The Http client instance to configure. :raises LinkedServiceException: If API key settings are missing. .. py:method:: _configure_custom_auth(http: ds_protocol_http_py_lib.utils.http.provider.Http) -> None 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. :param http: The Http client instance to configure. :raises AuthenticationError: If the token is missing in the response. :raises LinkedServiceException: If custom auth settings are missing. .. py:method:: _configure_noauth(_http: ds_protocol_http_py_lib.utils.http.provider.Http) -> None Configure no authentication. This is a no-op handler used to keep the auth dispatch table fully typed. :param _http: The Http client instance to configure. .. py:method:: connect() -> None 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. :rtype: None :raises AuthenticationError: If the authentication fails. :raises LinkedServiceException: If the auth_type is unsupported. .. py:method:: test_connection() -> tuple[bool, str] Test the connection to the HTTP API. :returns: A tuple containing a boolean indicating success and a string message. :rtype: tuple[bool, str] .. py:method:: close() -> None Close the linked service.