Middleware API Client

Python client for the FAIRagro Middleware API with certificate-based authentication (mTLS).

Features

✅ Certificate-based authentication (mutual TLS)
✅ Configuration via YAML files, environment variables, or Docker secrets
✅ Async context manager support
✅ Comprehensive error handling
✅ Type-safe with Pydantic models

Installation

This package is part of the FAIRagro Advanced Middleware project and uses local dependencies.

Quick Start

1. Create Configuration File

# config.yaml
log_level: INFO
api_url: https://your-api-server:8000
client_cert_path: /path/to/client-cert.pem
client_key_path: /path/to/client-key.pem
ca_cert_path: /path/to/ca-cert.pem  # optional
timeout: 30.0
verify_ssl: true

2. Use the Client

import asyncio
from pathlib import Path
from arctrl import ARC, ArcInvestigation
from middleware.api_client import Config, ApiClient


async def main():
    # Load configuration
    config = Config.from_yaml_file(Path("config.yaml"))

    # Create ARC object
    inv = ArcInvestigation.create(identifier="my-arc", title="My ARC")
    arc = ARC.from_arc_investigation(inv)

    # Use client with context manager
    async with ApiClient(config) as client:
        # Send a single ARC
        response = await client.create_or_update_arc(
            rdi="my-rdi",
            arc=arc,  # Can be ARC object, dict, or JSON string
        )
        print(f"ARC status: {response.status}")

        # Or run a harvest workflow
        async def arc_stream():
            yield arc  # Can yield ARC objects, dicts, or JSON strings

        harvest = await client.harvest_arcs(
            rdi="my-rdi",
            arcs=arc_stream(),
            expected_datasets=1,
        )
        print(f"Harvest status: {harvest.status}")


asyncio.run(main())

Configuration Options

Option	Type	Required	Default	Description
`log_level`	string	No	INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
`api_url`	string	Yes	-	Base URL of the Middleware API
`client_cert_path`	string	No	null	Path to client certificate (PEM format)
`client_key_path`	string	No	null	Path to client private key (PEM format)
`ca_cert_path`	string	No	null	Path to CA certificate for server verification
`timeout`	float	No	30.0	Request timeout in seconds
`verify_ssl`	bool	No	true	Enable SSL certificate verification
`max_concurrency`	int	No	10	Maximum concurrent API requests (also default for `harvest_arcs`)

API Methods

`create_or_update_arc(rdi: str, arc: ARC | dict | str) -> ArcResult`

Create or update one ARC in the Middleware API.

Parameters:

rdi (str): The RDI identifier (e.g., "edaphobase").
arc (ARC | dict | str): ARC object from arctrl, pre-serialised RO-Crate dict, or JSON string.

Returns:

ArcResult: Contains the result of the operation.

Raises:

ApiClientError: If the request fails due to HTTP errors, network issues, or invalid JSON.

Example:

from arctrl import ARC, ArcInvestigation

inv = ArcInvestigation.create(identifier="my-arc-001", title="My ARC")
arc = ARC.from_arc_investigation(inv)

response = await client.create_or_update_arc(
    rdi="edaphobase",
    arc=arc,  # Can also be dict or JSON string
)

`harvest_arcs(rdi: str, arcs: AsyncIterator[ARC | dict | str], expected_datasets: int | None = None) -> HarvestResult`

Convenience workflow to create a harvest, upload all ARCs from an async iterator, and complete the harvest.

Uses config.max_concurrency by default.
Continues on item-level submission errors and skips failed items.
Cancels the harvest only for catastrophic errors.
Supports ARC objects, pre-serialised RO-Crate dicts, and JSON strings.

All errors are raised as ApiClientError exceptions:

from middleware.api_client import ApiClientError

try:
    response = await client.create_or_update_arc(
        rdi="my-rdi",
        arc=arc,  # Can be ARC object, dict, or JSON string
    )
except ApiClientError as e:
    print(f"API Error: {e}")

Metadata

Release files for fairagro-middleware-api-client 11.1.1.dev33

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fairagro-middleware-api-client 11.1.1.dev33
File	Size	Uploaded	Provenance
fairagro_middleware_api_client-11.1.1.dev33.tar.gz	25.9 kB	Aug 5, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for fairagro-middleware-api-client 11.1.1.dev33
File	Interpreter	ABI	Platform	Reset
fairagro_middleware_api_client-11.1.1.dev33-py3-none-any.whl 14.8 kB Aug 5, 2026 Without provenance	Python 3	none	any	Details

Total release size: 40.6 kB

Release files / fairagro_middleware_api_client-11.1.1.dev33.tar.gz

Download URL	fairagro_middleware_api_client-11.1.1.dev33.tar.gz
Size	25.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`df947c3c652184692d72ffd3bf20e4ed519864da5d09adb42eb84368e02ab485`
BLAKE2b-256 checksum How to use checksums	`a78dd8113931f20e670b97a094219c0cea17c37f186128e4aa2152e48ee79ce5`
Upload date	Aug 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fairagro_middleware_api_client-11.1.1.dev33-py3-none-any.whl

Download URL	fairagro_middleware_api_client-11.1.1.dev33-py3-none-any.whl
Size	14.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`426c46dbe747efd2f1f2db18900cdcb0f1562e956118f0ce24ed7e74d57234c5`
BLAKE2b-256 checksum How to use checksums	`e1dc7380d02c9c3ff18489138c97a2608455bc72ea7b7529d3044c48aa1b6a83`
Upload date	Aug 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Security for fairagro-middleware-api-client 11.1.1.dev33

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.