API Clients¶

The SDK provides both synchronous and asynchronous API clients for interacting with the Upassist Cloud API. The clients automatically handle URL construction by prepending the base API URL to relative paths.

Features¶

Synchronous client for simple use cases
Asynchronous client for high-performance applications
Automatic retry and error handling
Type-safe API responses
Automatic base URL handling

Examples¶

Synchronous Client¶

Use the synchronous client for simple operations

from upassist import SyncAPIClient

# Create a synchronous client
client = SyncAPIClient(api_key="your-api-key")

# Make API requests - base URL is automatically prepended
response = client.get("/heartbeats")  # Calls https://api.upassist.cloud/v1/heartbeats
response = client.get("heartbeats")   # Same as above

# Full URLs are used as-is
response = client.get("https://custom-api.upassist.cloud/v1/heartbeats")

Asynchronous Client¶

Use the asynchronous client for high-performance operations

from upassist import AsyncAPIClient
import asyncio

async def main():
    # Create an asynchronous client
    client = AsyncAPIClient(api_key="your-api-key")

    # Make concurrent API requests - base URL is automatically prepended
    responses = await asyncio.gather(
        client.get("/heartbeats"),     # Calls https://api.upassist.cloud/v1/heartbeats
        client.get("logs"),            # Calls https://api.upassist.cloud/v1/logs
        client.get("https://custom-api.upassist.cloud/v1/metrics")  # Uses full URL
    )

    # Process responses
    heartbeats, logs, metrics = [r.json() for r in responses]

# Run the async code
asyncio.run(main())

Error Handling¶

Handle API errors gracefully

from upassist import SyncAPIClient
from upassist.exceptions import APIError

client = SyncAPIClient(api_key="your-api-key")

try:
    response = client.get("/heartbeats")
except APIError as e:
    print(f"API Error: {e}")
    # Handle the error appropriately

API Reference¶

`AbstractAPIClient` ¶

Bases: ABC

Base class for API clients that provides common functionality for making HTTP requests.

This abstract class defines the interface and common functionality for API clients. It handles authentication, request formatting, and provides convenience methods for different HTTP methods.

The client can be initialized with an API key and version, or it will use the values from the config module if not provided.

Example

from upassist import config
from upassist.client import YourAPIClient

# Initialize with config values
client = YourAPIClient()  # Uses config.API_KEY and config.API_VERSION

# Or override config values
client = YourAPIClient(
    api_key="your-api-key",
    api_version="v1"
)

# Make requests using convenience methods
response = client.get('users', params={'page': 1})
response = client.post('users', json={'name': 'John'})
response = client.delete('users/123')

# Or use the base request method
response = client.request(
    method='GET',
    url='users',
    params={'page': 1}
)

Source code in upassist/client/abstract.py

class AbstractAPIClient(ABC):
    """Base class for API clients that provides common functionality for making HTTP requests.

    This abstract class defines the interface and common functionality for API clients.
    It handles authentication, request formatting, and provides convenience methods
    for different HTTP methods.

    The client can be initialized with an API key and version, or it will use the values
    from the config module if not provided.

    Example:
        ```python
        from upassist import config
        from upassist.client import YourAPIClient

        # Initialize with config values
        client = YourAPIClient()  # Uses config.API_KEY and config.API_VERSION

        # Or override config values
        client = YourAPIClient(
            api_key="your-api-key",
            api_version="v1"
        )

        # Make requests using convenience methods
        response = client.get('users', params={'page': 1})
        response = client.post('users', json={'name': 'John'})
        response = client.delete('users/123')

        # Or use the base request method
        response = client.request(
            method='GET',
            url='users',
            params={'page': 1}
        )
        ```
    """

    def __init__(self, api_key: str | None = None, api_version: str | None = None):
        """Initialize the API client.

        Args:
            api_key: Optional API key. If not provided, uses config.API_KEY
            api_version: Optional API version. If not provided, uses config.API_VERSION
        """
        self._check_required_packages()
        self.api_key = api_key or config.API_KEY
        self.api_version = api_version or config.API_VERSION

    @property
    def base_api_url(self) -> str:
        return f"https://api.upassist.cloud/{self.api_version}"

    @abstractmethod
    def _check_required_packages(self) -> None:
        return

    @abstractmethod
    def _request(
        self,
        method: str,
        url: str,
        params: dict | None = None,
        headers: dict | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
    ) -> Any:
        return

    def request(
        self,
        method: str,
        url: str,
        params: dict | None = None,
        headers: dict | None = None,
        json: dict[Any, Any] | list[Any] | None = None,
    ) -> Any:
        if headers is None:
            headers = {}
        if self.api_key:
            headers["Authorization"] = f"Bearer {self.api_key}"

        # Prepend base_api_url if URL doesn't start with http
        if not url.startswith(("http://", "https://")):
            url = f"{self.base_api_url}/{url.lstrip('/')}"

        return self._request(
            method=method,
            url=url,
            params=params,
            headers=headers,
            json=json,
        )

    def get(self, url: str, params: dict | None = None, headers: dict | None = None) -> Any:
        return self.request(method="GET", url=url, params=params, headers=headers)

    def post(
        self,
        url: str,
        json: dict[Any, Any] | list[Any] | None = None,
        params: dict | None = None,
        headers: dict | None = None,
    ) -> Any:
        return self.request(method="POST", url=url, json=json, params=params, headers=headers)

    def put(
        self,
        url: str,
        json: dict[Any, Any] | list[Any] | None = None,
        params: dict | None = None,
        headers: dict | None = None,
    ) -> Any:
        return self.request(method="PUT", url=url, json=json, params=params, headers=headers)

    def patch(
        self,
        url: str,
        json: dict[Any, Any] | list[Any] | None = None,
        params: dict | None = None,
        headers: dict | None = None,
    ) -> Any:
        return self.request(method="PATCH", url=url, json=json, params=params, headers=headers)

    def delete(self, url: str, params: dict | None = None, headers: dict | None = None) -> Any:
        return self.request(method="DELETE", url=url, params=params, headers=headers)

    def head(self, url: str, params: dict | None = None, headers: dict | None = None) -> Any:
        return self.request(method="HEAD", url=url, params=params, headers=headers)

    def options(self, url: str, params: dict | None = None, headers: dict | None = None) -> Any:
        return self.request(method="OPTIONS", url=url, params=params, headers=headers)

`init(api_key=None, api_version=None)` ¶

Initialize the API client.

Parameters:

Name	Type	Description	Default
`api_key`	`str \| None`	Optional API key. If not provided, uses config.API_KEY	`None`
`api_version`	`str \| None`	Optional API version. If not provided, uses config.API_VERSION	`None`