Architecture Overview

The SDK is organized around a core HTTP client layer, endpoint wrappers that model the iMednet API, workflow helpers that combine multiple endpoint calls, and a CLI built on top of those pieces.

Components

graph TD CLI[CLI] --> |invokes| Workflows Workflows --> |coordinate| Endpoints Endpoints --> |use| Client["(HTTP Client)"] Client --> |requests| API

Core Client

The synchronous Client implements authentication, retry handling, and JSON serialization for each API request. It inherits from HTTPClientBase and is shared by all endpoint classes.

Async Client

AsyncClient provides the same features as the sync client but leverages async/await for concurrency. The ImednetSDK exposes both clients via sdk.client and sdk.async_client.

Endpoints

Each endpoint, such as StudiesEndpoint, wraps a related set of API operations. Endpoints can cache responses when called without filters and expose list/get methods that return typed models.

Workflows

Workflows orchestrate several endpoints to perform higher level tasks. For example, RecordUpdateWorkflow validates record payloads, submits them, and polls resulting jobs. Workflows have sync and async variants and are available under sdk.workflows.

Caching

Caching Behavior describes how endpoint and schema data are cached. Cached values can be refreshed by passing refresh=True to endpoint methods or calling schema.refresh() on a validator.

CLI

The Command Line Interface (CLI) uses Typer to expose common workflows on the command line. Each command creates an ImednetSDK instance, invokes a workflow, and closes the SDK when finished.

Data Flow

graph LR User --> |runs| CLI User --> |imports| SDK CLI --> |uses| Workflows SDK --> |exposes| Endpoints Workflows --> |call| Endpoints Endpoints --> |delegate| Client Client --> |talks to| API Client --> |uses| Cache["(Caches)"]

Extension Points

graph TD BaseEndpoint --> NewEndpoint[Custom Endpoint] Workflows --> NewWorkflow[Custom Workflow] NewEndpoint --> |register| SDK NewWorkflow --> |expose via| CLI

Adding New Endpoints

  • Subclass BaseEndpoint.

  • Register the class in _ENDPOINT_REGISTRY within imednet.sdk so ImednetSDK exposes it.

  • Document the endpoint in docs/endpoints/ and add tests.

Adding New Workflows

  • Create a workflow under imednet/workflows and provide sync and async methods where appropriate.

  • Instantiate the workflow in Workflows inside imednet.sdk.

  • Add CLI commands or examples that demonstrate the workflow.

  • Update documentation and tests.