Base API Classes

This section covers the foundational classes that provide common functionality for all API endpoints.

Base API

class datamint.api.base_api.ApiConfig(server_url, api_key=None, timeout=30.0, max_retries=3, port=None, verify_ssl=True)

Bases: object

Configuration for API client.

server_url: Base URL for the API.

api_key: Optional API key for authentication.

timeout: Request timeout in seconds.

max_retries: Maximum number of retries for requests.

port: Optional port number for the API server.

verify_ssl: Whether to verify SSL certificates. Default is True. Set to False only in development environments with self-signed certificates. Can also be a path to a CA bundle file.

Parameters:

server_url (str)
api_key (str | None)
timeout (float)
max_retries (int)
port (int | None)
verify_ssl (bool | str)

api_key: str | None = None

max_retries: int = 3

port: int | None = None

server_url: str

timeout: float = 30.0

verify_ssl: bool | str = True

property web_app_url: str: Get the base URL for the web application.

class datamint.api.base_api.BaseApi(config, client=None)

Bases: object

Base class for all API endpoint handlers.

Parameters:

config (ApiConfig)
client (Client | None)

__del__(): Destructor - ensures client is closed when instance is garbage collected.

__enter__(): Context manager entry.

__exit__(exc_type, exc_val, exc_tb): Context manager exit - ensures client is closed.

close()

Close the HTTP client and release resources.

Should be called when the API instance is no longer needed. Only closes the client if it was created by this instance.

Return type:: None

static convert_format(bytes_array, mimetype=None, file_path=None)

Convert the bytes array to the appropriate format based on the mimetype.

Parameters:

bytes_array (bytes) – Raw file content bytes
mimetype (str | None) – Optional MIME type of the content
file_path (str | None) – deprecated

Return type:

ImagingData | bytes

Returns:

Converted content in appropriate format (pydicom.Dataset, PIL Image, cv2.VideoCapture, …)

Example

>>> fpath = 'path/to/file.dcm'
>>> with open(fpath, 'rb') as f:
...     dicom_bytes = f.read()
>>> dicom = BaseApi.convert_format(dicom_bytes)

static get_status_code(e)

Parameters:: e (HTTPError | ClientError)
Return type:: int

Entity Base API

class datamint.api.entity_base_api.CRUDEntityApi(config, entity_class, endpoint_base, client=None)

Bases: CreatableEntityApi[T], UpdatableEntityApi[T], DeletableEntityApi[T]

Full CRUD API handler for entities supporting create, read, update, delete operations.

Parameters:

config (ApiConfig)
entity_class (type[TypeVar(T, bound= BaseEntity)])
endpoint_base (str)
client (Client | None)

class datamint.api.entity_base_api.CreatableEntityApi(config, entity_class, endpoint_base, client=None)

Bases: EntityBaseApi[T]

Extension of EntityBaseApi for entities that support creation.

This class adds methods to handle creation of new entities.

Parameters:

config (ApiConfig)
entity_class (type[TypeVar(T, bound= BaseEntity)])
endpoint_base (str)
client (Client | None)

create(*args, return_entity=True, **kwargs)

Parameters:: return_entity (bool)
Return type:: str | TypeVar(T, bound= BaseEntity)

class datamint.api.entity_base_api.DeletableEntityApi(config, entity_class, endpoint_base, client=None)

Bases: EntityBaseApi[T]

Extension of EntityBaseApi for entities that support soft deletion.

This class adds methods to handle soft-deleted entities, allowing retrieval and restoration of such entities.

Parameters:

config (ApiConfig)
entity_class (type[TypeVar(T, bound= BaseEntity)])
endpoint_base (str)
client (Client | None)

bulk_delete(entities)

Delete multiple entities.

Parameters:: entities (Sequence[str | TypeVar(T, bound= BaseEntity)]) – Sequence of unique identifiers for the entities to delete or the entity instances themselves.
Raises:: httpx.HTTPStatusError – If deletion fails or any entity not found
Return type:: None

delete(entity)

Delete an entity.

Parameters:: entity (str | TypeVar(T, bound= BaseEntity)) – Unique identifier for the entity to delete or the entity instance itself.
Raises:: httpx.HTTPStatusError – If deletion fails or entity not found
Return type:: None

class datamint.api.entity_base_api.EntityBaseApi(config, entity_class, endpoint_base, client=None)

Bases: BaseApi, Generic[T]

Base API handler for entity-related endpoints with CRUD operations.

This class provides a template for API handlers that work with specific entity types, offering common CRUD operations with proper typing.

Type Parameters:: T: The entity type this API handler manages (must extend BaseEntity)

Parameters:

config (ApiConfig)
entity_class (type[TypeVar(T, bound= BaseEntity)])
endpoint_base (str)
client (Client | None)

get_all(limit=None)

Get all entities with optional pagination and filtering.

Return type:: Sequence[TypeVar(T, bound= BaseEntity)]
Returns:: List of entity instances
Raises:: httpx.HTTPStatusError – If the request fails
Parameters:: limit (int | None)

get_by_id(entity_id)

Get a specific entity by its ID.

Parameters:: entity_id (str) – Unique identifier for the entity.
Return type:: TypeVar(T, bound= BaseEntity)
Returns:: Entity instance.
Raises:: httpx.HTTPStatusError – If the entity is not found or request fails.

get_list(limit=None, **kwargs)

Get entities with optional filtering.

Return type:: Sequence[TypeVar(T, bound= BaseEntity)]
Returns:: List of entity instances.
Raises:: httpx.HTTPStatusError – If the request fails.
Parameters:: limit (int | None)

class datamint.api.entity_base_api.UpdatableEntityApi(config, entity_class, endpoint_base, client=None)

Bases: EntityBaseApi[T]

Parameters:

config (ApiConfig)
entity_class (type[TypeVar(T, bound= BaseEntity)])
endpoint_base (str)
client (Client | None)

partial_update(entity, entity_data)

Alias for patch() to partially update an entity.

Parameters:

entity (str | TypeVar(T, bound= BaseEntity))
entity_data (dict[str, Any])

patch(entity, entity_data)

Partially update an existing entity.

Parameters:

entity (str | TypeVar(T, bound= BaseEntity)) – Unique identifier for the entity or the entity instance.
entity_data (dict[str, Any]) – Dictionary containing fields to update. Only provided fields will be updated.

Returns:

Updated entity instance.

Raises:

httpx.HTTPStatusError – If update fails or entity not found.