# mikewooster/api-client architecture

> Architecture diagram of the GitHub repository mikewooster/api-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikewooster/api-client
- Repository: https://github.com/mikewooster/api-client

## Overview

This is a Python HTTP API-client library: users define endpoint methods on an APIClient subclass, then invoke them to send requests and receive parsed results or domain-specific errors. The core path runs through a configurable request strategy, HTTP transport, response abstraction, and response handler. Authentication, request formatting, retries, pagination, and endpoint decorators are distinct extension capabilities. The map follows the sampled client and strategy code; README-documented features with unsampled implementations are shown with unverified links.

Main entry points: [`apiclient/client.py`](https://github.com/mikewooster/api-client/blob/master/apiclient/client.py) (APIClient), [`apiclient/request_strategies.py`](https://github.com/mikewooster/api-client/blob/master/apiclient/request_strategies.py) (Request Strategy), [`apiclient/error_handlers.py`](https://github.com/mikewooster/api-client/blob/master/apiclient/error_handlers.py) (Error Handler), [`apiclient/response_handlers.py`](https://github.com/mikewooster/api-client/blob/master/apiclient/response_handlers.py) (Response Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Interface"]
  node_api["APIClient<br/>[client.py]"]
  node_endpoint["Endpoint Decorator<br/>[decorates.py]"]
end

subgraph group_request["Request Pipeline"]
  node_auth["Authentication"]
  node_formatter["Request Formatter"]
  node_strategy["Request Strategy"]
end

subgraph group_response["Response Handling"]
  node_response["Response Adapter<br/>[response.py]"]
  node_response_handler["Response Handler"]
  node_error_handler["Error Handler<br/>[error_handlers.py]"]
  node_exceptions["Client Exceptions<br/>[exceptions.py]"]
end

subgraph group_extensions["Client Extensions"]
  node_pagination["Pagination Decorator<br/>[paginators.py]"]
  node_retry["Retry Decorator<br/>[retrying.py]"]
  node_types["Shared Types<br/>[typing.py]"]
end

node_user(("API Consumer"))
node_remote(("API Service"))

node_user -->|"calls endpoints"| node_api
node_api -->|"initializes and reads"| node_auth
node_api -->|"configures and reads"| node_formatter
node_api -->|"sets and dispatches"| node_strategy
node_api -->|"configures handler"| node_response_handler
node_api -->|"configures handler"| node_error_handler
node_api -.->|"uses decorator"| node_endpoint
node_strategy -->|"reads client settings"| node_api
node_strategy -->|"formats request data"| node_formatter
node_strategy -->|"sends HTTP requests"| node_remote
node_remote -->|"returns HTTP response"| node_strategy
node_strategy -->|"wraps response"| node_response
node_strategy -->|"decodes response"| node_response_handler
node_strategy -->|"delegates failures"| node_error_handler
node_response_handler -->|"reads response data"| node_response
node_error_handler -->|"reads status and body"| node_response
node_error_handler -->|"creates request errors"| node_exceptions
node_pagination -->|"selects paginated strategy"| node_strategy
node_retry -.->|"wraps request methods"| node_api
node_api -->|"uses request types"| node_types

click node_api "https://github.com/mikewooster/api-client/blob/master/apiclient/client.py"
click node_endpoint "https://github.com/mikewooster/api-client/blob/master/apiclient/decorates.py"
click node_auth "https://github.com/mikewooster/api-client/blob/master/apiclient/authentication_methods.py"
click node_formatter "https://github.com/mikewooster/api-client/blob/master/apiclient/request_formatters.py"
click node_strategy "https://github.com/mikewooster/api-client/blob/master/apiclient/request_strategies.py"
click node_response "https://github.com/mikewooster/api-client/blob/master/apiclient/response.py"
click node_response_handler "https://github.com/mikewooster/api-client/blob/master/apiclient/response_handlers.py"
click node_error_handler "https://github.com/mikewooster/api-client/blob/master/apiclient/error_handlers.py"
click node_exceptions "https://github.com/mikewooster/api-client/blob/master/apiclient/exceptions.py"
click node_pagination "https://github.com/mikewooster/api-client/blob/master/apiclient/paginators.py"
click node_retry "https://github.com/mikewooster/api-client/blob/master/apiclient/retrying.py"
click node_types "https://github.com/mikewooster/api-client/blob/master/apiclient/utils/typing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_endpoint toneBlue
class node_auth,node_formatter,node_strategy toneAmber
class node_response,node_response_handler,node_error_handler,node_exceptions,node_user,node_remote toneMint
class node_pagination,node_retry,node_types toneRose
```

## Components

### Client Interface

- [APIClient](https://github.com/mikewooster/api-client/blob/master/apiclient/client.py): `apiclient/client.py`
- [Endpoint Decorator](https://github.com/mikewooster/api-client/blob/master/apiclient/decorates.py): `apiclient/decorates.py`

### Request Pipeline

- [Authentication](https://github.com/mikewooster/api-client/blob/master/apiclient/authentication_methods.py): `apiclient/authentication_methods.py`
- [Request Formatter](https://github.com/mikewooster/api-client/blob/master/apiclient/request_formatters.py): `apiclient/request_formatters.py`
- [Request Strategy](https://github.com/mikewooster/api-client/blob/master/apiclient/request_strategies.py): `apiclient/request_strategies.py`

### Response Handling

- [Response Adapter](https://github.com/mikewooster/api-client/blob/master/apiclient/response.py): `apiclient/response.py`
- [Response Handler](https://github.com/mikewooster/api-client/blob/master/apiclient/response_handlers.py): `apiclient/response_handlers.py`
- [Error Handler](https://github.com/mikewooster/api-client/blob/master/apiclient/error_handlers.py): `apiclient/error_handlers.py`
- [Client Exceptions](https://github.com/mikewooster/api-client/blob/master/apiclient/exceptions.py): `apiclient/exceptions.py`

### Client Extensions

- [Pagination Decorator](https://github.com/mikewooster/api-client/blob/master/apiclient/paginators.py): `apiclient/paginators.py`
- [Retry Decorator](https://github.com/mikewooster/api-client/blob/master/apiclient/retrying.py): `apiclient/retrying.py`
- [Shared Types](https://github.com/mikewooster/api-client/blob/master/apiclient/utils/typing.py): `apiclient/utils/typing.py`

### Other components

- **API Consumer**
- **API Service**

## Connections

- API Consumer → APIClient: calls endpoints (evidence: `README.md`)
- APIClient → Authentication: initializes and reads (evidence: `apiclient/client.py`)
- APIClient → Request Formatter: configures and reads (evidence: `apiclient/client.py`)
- APIClient → Request Strategy: sets and dispatches (evidence: `apiclient/client.py`)
- APIClient → Response Handler: configures handler (evidence: `apiclient/client.py`)
- APIClient → Error Handler: configures handler (evidence: `apiclient/client.py`)
- APIClient → Endpoint Decorator: uses decorator (evidence: `README.md`)
- Request Strategy → APIClient: reads client settings (evidence: `apiclient/request_strategies.py`)
- Request Strategy → Request Formatter: formats request data (evidence: `apiclient/request_strategies.py`)
- Request Strategy → API Service: sends HTTP requests (evidence: `apiclient/request_strategies.py`)
- API Service → Request Strategy: returns HTTP response (evidence: `apiclient/request_strategies.py`)
- Request Strategy → Response Adapter: wraps response (evidence: `apiclient/request_strategies.py`)
- Request Strategy → Response Handler: decodes response (evidence: `apiclient/request_strategies.py`)
- Request Strategy → Error Handler: delegates failures (evidence: `apiclient/request_strategies.py`)
- Response Handler → Response Adapter: reads response data (evidence: `apiclient/response_handlers.py`)
- Error Handler → Response Adapter: reads status and body (evidence: `apiclient/error_handlers.py`)
- Error Handler → Client Exceptions: creates request errors (evidence: `apiclient/error_handlers.py`)
- Pagination Decorator → Request Strategy: selects paginated strategy (evidence: `apiclient/paginators.py`)
- Retry Decorator → APIClient: wraps request methods (evidence: `README.md`)
- APIClient → Shared Types: uses request types (evidence: `apiclient/client.py`)
