Base Classes

The base classes provide the foundation for all API resource objects.

BaseAPIObject

The base class that all API resource objects inherit from. It provides:

• Automatic attribute mapping from API responses

• Change tracking for efficient updates

• CRUD operations (create, read, update, delete)

• Class methods for querying and filtering

class betterstack.uptime.base.BaseAPIObject(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>)

Bases: object

Base class for all API objects using dataclasses.

This class provides common functionality for all BetterStack API objects: - Automatic attribute assignment from API responses - Change tracking for efficient updates (only modified fields are sent) - CRUD operations (fetch, save, delete) - Class methods for querying and creating objects

The hybrid approach stores known fields as dataclass fields with proper types, while unknown fields from the API are stored in the _extras dictionary.

Attributes:

id: The unique identifier for this object. _api: Reference to the API client (excluded from repr/compare). _extras: Dictionary for storing unknown API attributes. _original_values: Snapshot of values when object was loaded/saved.

id: str

get_modified_properties() → list[str]

Return list of modified property names since last save/fetch.

Returns:

List of attribute names that have been modified.

reset_variable_tracking() → None

Reset change tracking to current state.

generate_url() → str

Create the URL for this specific instance.

Returns:

Full instance URL path.

classmethod generate_global_url() → str

Get the collection URL for this object type.

Returns:

Collection URL path.

fetch_data(**kwargs: Any) → None

Fetch all attributes from the API.

Args:

**kwargs: Additional parameters for the API request.

save() → None

Update all changed attributes on the API.

Only sends modified attributes to minimize API payload.

delete() → None

Delete this object from the API.

classmethod get_or_create(api: PaginatedAPI, **kwargs: Any) → tuple[bool, Self]

Get an existing object or create a new one.

Attempts to find an object matching the given attributes. If no match is found, creates a new object with those attributes.

Args:

api: API instance. **kwargs: Attributes to search for or use when creating.

Returns:

Tuple of (created: bool, object: BaseAPIObject). created is True if a new object was created.

Raises:

ValueError: If multiple objects match the criteria.

classmethod new(api: PaginatedAPI, **kwargs: Any) → Self

Create a new object on the API.

Args:

api: API instance. **kwargs: Attributes for the new object.

Returns:

The newly created object.

classmethod filter(api: PaginatedAPI, **kwargs: Any) → Generator[Self, None, None]

Filter objects using URL query parameters.

Args:

api: API instance with pagination support. **kwargs: Query parameters to filter by.

Yields:

Objects matching the filter criteria.

Raises:

ValidationError: If a filter parameter is not allowed.

classmethod get_all_instances(api: PaginatedAPI) → Generator[Self, None, None]

Fetch all objects of this type from the API.

Args:

api: API instance with pagination support.

Yields:

All objects of this type.

__init__(id: str, _api: PaginatedAPI, _extras: dict[str, Any]=<factory>, _original_values: dict[str, Any]=<factory>) → None

Common Operations

All objects inheriting from BaseAPIObject support these operations:

Fetching All Instances

from betterstack.uptime import UptimeAPI
from betterstack.uptime.objects import Monitor

api = UptimeAPI("your-token")

# Returns a generator that handles pagination automatically
for monitor in Monitor.get_all_instances(api):
    print(monitor.url)

Getting or Creating

# Get existing object or create new one
created, monitor = Monitor.get_or_create(
    api,
    url="https://example.com",
    monitor_type="status",
)

if created:
    print("New monitor created")
else:
    print("Existing monitor found")

Modifying and Saving

# Only modified fields are sent to the API
monitor.paused = True
monitor.check_frequency = 60
monitor.save()

# Check what was modified
print(monitor.get_modified_properties())

Deleting

monitor.delete()

Filtering

# Filter using API query parameters
incidents = Incident.filter(api, monitor_id=12345)

for incident in incidents:
    print(incident.cause)