{"id":9477,"library":"apimatic-core-interfaces","title":"APIMatic Core Interfaces","description":"apimatic-core-interfaces provides an abstract layer of functionalities for APIMatic's core library, HTTP client adapters, and generated SDKs. It defines standard interfaces (Abstract Base Classes) for components like HTTP clients, loggers, and authentication managers. The current version is 0.1.8, with irregular but frequent minor releases introducing new interface definitions.","status":"active","version":"0.1.8","language":"en","source_language":"en","source_url":"https://github.com/apimatic/core-interfaces-python","tags":["api","sdk","interfaces","abstract","http","client","apimatic"],"install":[{"cmd":"pip install apimatic-core-interfaces","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"IHttpClient","correct":"from apimatic_core_interfaces.client.http.http_client import IHttpClient"},{"symbol":"HttpRequest","correct":"from apimatic_core_interfaces.client.http.request import HttpRequest"},{"symbol":"HttpResponse","correct":"from apimatic_core_interfaces.client.http.response import HttpResponse"},{"symbol":"HttpContext","correct":"from apimatic_core_interfaces.client.http.http_context import HttpContext"},{"symbol":"ILogger","correct":"from apimatic_core_interfaces.logger.logger import ILogger"},{"symbol":"IAuthManager","correct":"from apimatic_core_interfaces.authentication.auth_manager import IAuthManager"}],"quickstart":{"code":"import abc\nfrom apimatic_core_interfaces.client.http.http_client import IHttpClient\nfrom apimatic_core_interfaces.client.http.request import HttpRequest\nfrom apimatic_core_interfaces.client.http.response import HttpResponse\nfrom apimatic_core_interfaces.client.http.http_context import HttpContext\nfrom typing import Any # Used for type hinting a generic raw response\n\nclass CustomHttpClient(IHttpClient):\n    \"\"\"\n    A minimal custom HTTP client implementation demonstrating how to fulfill\n    the apimatic-core-interfaces. It shows how to implement the required methods.\n    This class would typically wrap an existing HTTP library like `requests` or `httpx`.\n    \"\"\"\n    def send(self, request: HttpRequest, context: HttpContext = None) -> HttpResponse:\n        print(f\"CustomHttpClient received request for: {request.query_url}\")\n        # Simulate a raw response object/dictionary from an underlying HTTP client.\n        # In a real scenario, this would involve making an actual HTTP call.\n        raw_response_mock = {\n            'status_code': 200,\n            'reason_phrase': 'OK',\n            'headers': {'Content-Type': 'application/json'},\n            'text': '{\"message\": \"Hello from custom client!\"}',\n            'request_method': request.method,\n            'request_url': request.query_url\n        }\n\n        # Convert the raw response using the provided interface method\n        return self.convert_response(raw_response_mock)\n\n    def convert_response(self, raw_response: Any) -> HttpResponse:\n        \"\"\"\n        Converts a raw HTTP client response (e.g., from `requests`, `httpx`, or a mock)\n        into an `HttpResponse` object as expected by APIMatic Core.\n        \"\"\"\n        return HttpResponse(\n            status_code=raw_response.get('status_code', 200),\n            reason_phrase=raw_response.get('reason_phrase', 'OK'),\n            headers=raw_response.get('headers', {}),\n            body=raw_response.get('text', ''),\n            request=HttpRequest(\n                method=raw_response.get('request_method', 'GET'),\n                path=raw_response.get('request_url', '/'),\n                query_url=raw_response.get('request_url', '/')\n            )\n        )\n\n# Example of how to use this custom client (uncomment to run):\n# my_custom_client = CustomHttpClient()\n# sample_request = HttpRequest(\n#     method='GET',\n#     path='/api/data',\n#     query_url='https://api.example.com/api/data',\n#     headers={'Accept': 'application/json'}\n# )\n# response = my_custom_client.send(sample_request)\n# print(f\"\\nCustom client got response - Status: {response.status_code}, Body: {response.body}\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.x.x (prior to 1.0.0)"},{"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.","message":"Attempting to instantiate an APIMatic interface (which are Python Abstract Base Classes) directly will result in a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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()`.","cause":"You are trying to create an instance of an abstract interface directly, which is not allowed.","error":"TypeError: Can't instantiate abstract class IHttpClient with abstract methods send, convert_response"},{"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.","cause":"Your custom implementation class (`MyCustomClient`) inherits from an APIMatic interface but has not implemented all the required abstract methods defined in that interface.","error":"TypeError: Can't instantiate abstract class MyCustomClient with abstract methods convert_response"},{"fix":"Double-check the import path. For `IHttpClient`, the correct path is `from apimatic_core_interfaces.client.http.http_client import IHttpClient`.","cause":"Incorrect import path used to import an APIMatic interface or related class.","error":"ModuleNotFoundError: No module named 'apimatic_core_interfaces.client.http_client'"}]}