APIMatic Core Library for Python

Common errors

• ModuleNotFoundError: No module named 'apimatic_core'

  cause The `apimatic-core` library is not installed in your Python environment.
  fix Run `pip install apimatic-core` to install the library.

• from apimatic_core.http.http_client import HttpClient # or similar import fails

  cause Attempting to import an abstract base class or an internal implementation that is not directly exposed or intended for direct instantiation.
  fix Most user-level interactions are with concrete implementations like `RequestsClient` or higher-level abstractions like `GlobalConfiguration` and `ApiException`. Consult the library's source code or a generated SDK's usage for specific concrete classes.

• ValueError: Invalid URL: No scheme supplied. Perhaps you meant http://...

  cause Often occurs when the base URL for an API call (usually set by a generated SDK) is misconfigured or missing a scheme (e.g., `http://` or `https://`). `apimatic-core` relies on `requests` which requires a valid URL.
  fix Ensure that the base URL configured for your generated SDK (or passed to any core HTTP client method) includes a valid scheme. Check your SDK's configuration or environment variables.

Warnings

• gotcha APIMatic Core is primarily an internal library for SDKs generated by APIMatic. While you can import and use its components directly, its main purpose is to provide a consistent base for generated code. If you're not using APIMatic to generate an SDK, you might find more direct HTTP client libraries (like `requests`) more suitable.
  Fix: Understand that direct usage is for advanced customization or debugging of generated SDKs. For general HTTP client needs, consider `requests`.
• deprecated Older versions of Python might not be fully supported. While `apimatic-core` aims for broad compatibility, recent releases (v0.2.18+) explicitly test for Python 3.12 and 3.13. Using significantly older Python versions (e.g., Python 3.7 or earlier) may lead to unexpected issues.
  Fix: Ensure you are using Python 3.8+ for optimal compatibility. Upgrade to a supported Python version if encountering compatibility errors.
• gotcha Modifying `GlobalConfiguration` directly affects *all* subsequent operations that use these global settings within your application's process. Be mindful of potential side effects, especially in multi-threaded environments or if different parts of your application require distinct API configurations.
  Fix: For highly specific client configurations, consider creating and passing a custom `RequestsClient` instance to the generated SDK's client constructor if supported, rather than relying solely on global settings.

Install

• pip install apimatic-core Install latest version

Imports

• GlobalConfiguration

  from apimatic_core.configurations.global_configuration import GlobalConfiguration

  Used to modify global settings for generated SDKs.
• ApiException

  from apimatic_core.exceptions.api_exception import ApiException

  Base exception class for API-specific errors.
• ApiHelper

  from apimatic_core.utilities.api_helper import ApiHelper

  Contains utility functions for API requests and responses.

Quickstart

This quickstart demonstrates how to configure global settings that would be utilized by an APIMatic-generated SDK. It also shows how to catch a generic `ApiException`, a common pattern when working with generated clients.

import os
from apimatic_core.configurations.global_configuration import GlobalConfiguration
from apimatic_core.http.requests_client.requests_client import RequestsClient

# This library is primarily used by generated SDKs. 
# Direct usage often involves configuring global settings 
# or handling generic exceptions.

# Example: Configure global HTTP client settings
GlobalConfiguration.set_timeout(30) # seconds
GlobalConfiguration.set_user_agent("MyCustomApp/1.0")
GlobalConfiguration.set_verify_ssl(True)

# Optionally provide a custom HTTP client instance
# GlobalConfiguration.set_http_client(RequestsClient())

print(f"Global API Timeout: {GlobalConfiguration.get_timeout()} seconds")
print(f"Global User-Agent: {GlobalConfiguration.get_user_agent()}")
print(f"Global SSL Verification: {GlobalConfiguration.get_verify_ssl()}")

# In a generated SDK, these settings would now apply.
# For example, if you had an SDK generated by APIMatic:
# from my_generated_sdk.client import MyClient
# client = MyClient()
# ... the client would use the configured settings

# Example for handling a generic API exception (would typically come from a generated SDK call)
try:
    # Simulate an operation that might raise an ApiException
    raise ApiException("Resource not found", 404, {'X-Request-ID': 'abc'})
except ApiException as e:
    print(f"Caught API Exception: {e.message} (Status: {e.response_code})")
    print(f"Headers: {e.response_headers}")