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)

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.

Parameters:

  • server_url (str)

  • api_key (str | None)

  • timeout (float)

  • max_retries (int)

api_key: str | None = None
max_retries: int = 3
server_url: str
timeout: float = 30.0
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:
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:

pydicom.dataset.Dataset | Image.Image | cv2.VideoCapture | nib_FileBasedImage | 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 (HTTPStatusError | ClientResponseError)

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, **kwargs)
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.