APIMatic Core Interfaces

Common errors

• TypeError: Can't instantiate abstract class IHttpClient with abstract methods send, convert_response

  cause You are trying to create an instance of an abstract interface directly, which is not allowed.
  fix You must define a concrete class that inherits from `IHttpClient` and implements all its abstract methods (`send` and `convert_response`) before you can instantiate it. For example, `my_client = MyCustomHttpClient()`.

• TypeError: Can't instantiate abstract class MyCustomClient with abstract methods convert_response

  cause Your custom implementation class (`MyCustomClient`) inherits from an APIMatic interface but has not implemented all the required abstract methods defined in that interface.
  fix Review the interface's definition (e.g., `IHttpClient`) and ensure that all abstract methods, such as `convert_response` and `send`, are implemented in your `MyCustomClient` class.

• ModuleNotFoundError: No module named 'apimatic_core_interfaces.client.http_client'

  cause Incorrect import path used to import an APIMatic interface or related class.
  fix Double-check the import path. For `IHttpClient`, the correct path is `from apimatic_core_interfaces.client.http.http_client import IHttpClient`.

Warnings

• breaking Adding new abstract methods to existing interfaces (e.g., `IHttpClient`, `ILogger`) in minor version updates can break custom implementations that inherit from these interfaces but do not implement the newly added methods.
  Fix: Always check release notes for new abstract methods when upgrading and ensure all custom implementations are updated accordingly. Consider pinning to exact minor versions for production.
• gotcha Attempting to instantiate an APIMatic interface (which are Python Abstract Base Classes) directly will result in a `TypeError`.
  Fix: Interfaces must be inherited by a concrete class, and all their abstract methods must be implemented before the concrete class can be instantiated. For example, `client = CustomHttpClient()` is correct, `client = IHttpClient()` is wrong.
• gotcha A concrete class inheriting from an APIMatic interface must implement *all* abstract methods defined by that interface. Failing to do so will prevent the concrete class from being instantiated.
  Fix: Ensure your custom implementation class defines and implements every method marked as abstract in the interface it inherits from (e.g., `send` and `convert_response` for `IHttpClient`). The Python interpreter will raise a `TypeError` if any are missing.

Install

• pip install apimatic-core-interfaces Install stable version

Imports

• IHttpClient

  from apimatic_core_interfaces.client.http.http_client import IHttpClient

• HttpRequest

  from apimatic_core_interfaces.client.http.request import HttpRequest

• HttpResponse

  from apimatic_core_interfaces.client.http.response import HttpResponse

• HttpContext

  from apimatic_core_interfaces.client.http.http_context import HttpContext

• ILogger

  from apimatic_core_interfaces.logger.logger import ILogger

• IAuthManager

  from apimatic_core_interfaces.authentication.auth_manager import IAuthManager

Quickstart

This example demonstrates how to implement the `IHttpClient` interface, which is a common requirement when extending or customizing APIMatic SDK behavior. It defines a `CustomHttpClient` class that fulfills the `send` and `convert_response` abstract methods. In a real application, the `send` method would perform an actual HTTP request, and `convert_response` would adapt the underlying library's response object to `apimatic_core_interfaces.client.http.HttpResponse`.

import abc
from apimatic_core_interfaces.client.http.http_client import IHttpClient
from apimatic_core_interfaces.client.http.request import HttpRequest
from apimatic_core_interfaces.client.http.response import HttpResponse
from apimatic_core_interfaces.client.http.http_context import HttpContext
from typing import Any # Used for type hinting a generic raw response

class CustomHttpClient(IHttpClient):
    """
    A minimal custom HTTP client implementation demonstrating how to fulfill
    the apimatic-core-interfaces. It shows how to implement the required methods.
    This class would typically wrap an existing HTTP library like `requests` or `httpx`.
    """
    def send(self, request: HttpRequest, context: HttpContext = None) -> HttpResponse:
        print(f"CustomHttpClient received request for: {request.query_url}")
        # Simulate a raw response object/dictionary from an underlying HTTP client.
        # In a real scenario, this would involve making an actual HTTP call.
        raw_response_mock = {
            'status_code': 200,
            'reason_phrase': 'OK',
            'headers': {'Content-Type': 'application/json'},
            'text': '{"message": "Hello from custom client!"}',
            'request_method': request.method,
            'request_url': request.query_url
        }

        # Convert the raw response using the provided interface method
        return self.convert_response(raw_response_mock)

    def convert_response(self, raw_response: Any) -> HttpResponse:
        """
        Converts a raw HTTP client response (e.g., from `requests`, `httpx`, or a mock)
        into an `HttpResponse` object as expected by APIMatic Core.
        """
        return HttpResponse(
            status_code=raw_response.get('status_code', 200),
            reason_phrase=raw_response.get('reason_phrase', 'OK'),
            headers=raw_response.get('headers', {}),
            body=raw_response.get('text', ''),
            request=HttpRequest(
                method=raw_response.get('request_method', 'GET'),
                path=raw_response.get('request_url', '/'),
                query_url=raw_response.get('request_url', '/')
            )
        )

# Example of how to use this custom client (uncomment to run):
# my_custom_client = CustomHttpClient()
# sample_request = HttpRequest(
#     method='GET',
#     path='/api/data',
#     query_url='https://api.example.com/api/data',
#     headers={'Accept': 'application/json'}
# )
# response = my_custom_client.send(sample_request)
# print(f"\nCustom client got response - Status: {response.status_code}, Body: {response.body}")