# jeandemeusy/api-lib architecture

> Architecture diagram of the GitHub repository jeandemeusy/api-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeandemeusy/api-lib
- Repository: https://github.com/jeandemeusy/api-lib

## Overview

##### Project type and purpose
- This is an open-source Python library (“api-lib”) whose sole purpose is to simplify both building and consuming HTTP-based APIs.
- It provides core client functionality (in src/api_lib/api_lib.py), pluggable request headers, HTTP method abstractions, and object (de)serialization for requests and responses.

##### File structure
- Top-level:
- src/api_lib/ – the library code
­– api_lib.py: core ApiLib base class and request/response orchestration
­– headers/: header-building subpackage (Accept, Authorization, generic Header class)
­– method.py: HTTP method enum or constants
­– objects/: request/response object definitions (Request, Response)
- test/: unit tests and fixtures for every submodule
- CI & config (GitHub Actions, Makefile, pyproject.toml, etc.)

##### Insights from README
- The ApiLib class is designed for subclassing by concrete APIs (e.g., GithubAPI).
- Users supply base URL and authentication headers; they define async methods that call `self.req(Method, path, Model)` to marshal responses.
- Extensibility points: headers list, custom request/response models.

##### Main components and how they interact
a. ApiLib Core
­– Orchestrates HTTP calls, serializes request models, deserializes response models.
­– Exposes a generic `req(method, path, model)` async API.
b. Header Factory Subsystem
­– A set of Header classes (Accept, Authorization) that generate HTTP headers at runtime.
­– Injected into ApiLib via the `headers` attribute or constructor.
c. Method Definition
­– Enumeration or constants for HTTP methods (GET, POST, etc.).
d. Object (De)serialization
­– Request/Response model classes under objects/ that map JSON payloads to typed Python objects.
e. HTTP Transport Layer (implicit)
­– The underlying HTTP client (e.g., aiohttp or httpx – may be hidden or pluggable).
f. External API Service
­– Any upstream REST API endpoint (e.g., GitHub API).

##### Architectural patterns & design principles
- Separation of concerns: transport vs. header generation vs. business models.
- Strategy/Factory pattern: pluggable Header classes.
- Template Method: ApiLib defines the request flow; concrete subclasses supply endpoints and models.
- Async I/O: non-blocking HTTP calls (as indicated by async/await usage).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client Application"]:::external

    %% ApiLib Core and subcomponents
    subgraph "ApiLib Library" 
        ApiLibCore["ApiLib Core Module"]:::coreLib
        subgraph "Header Factory Subpackage"
            headerFactory["Header Factory"]:::coreLib
            Accept["Accept Header"]:::coreLib
            Authorization["Authorization Header"]:::coreLib
            BaseHeader["Header Base Class"]:::coreLib
        end
        MethodEnum["HTTP Method Definitions"]:::coreLib
        subgraph "Object Models Subpackage"
            RequestModel["Request Model"]:::coreLib
            ResponseModel["Response Model"]:::coreLib
        end
    end

    %% External dependencies
    HTTPTransport["HTTP Transport Layer\n(aiohttp/httpx)"]:::external
    ExternalAPI["External REST API"]:::external

    %% Connections
    Client -->|"instantiate & call req()"| ApiLibCore
    ApiLibCore -->|"get headers"| headerFactory
    headerFactory --> Accept
    headerFactory --> Authorization
    headerFactory --> BaseHeader
    ApiLibCore -->|"determine HTTP verb"| MethodEnum
    ApiLibCore -->|"serialize/deserialize"| RequestModel
    ApiLibCore -->|"serialize/deserialize"| ResponseModel
    ApiLibCore -->|"send HTTP request"| HTTPTransport
    HTTPTransport -->|"actual network call"| ExternalAPI
    ExternalAPI -->|"return JSON payload"| HTTPTransport
    HTTPTransport -->|"response JSON"| ApiLibCore
    ApiLibCore -->|"return typed model"| Client

    %% Click Events
    click ApiLibCore "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/api_lib.py"
    click headerFactory "https://github.com/jeandemeusy/api-lib/tree/master/src/api_lib/headers/"
    click Accept "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/headers/accept.py"
    click Authorization "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/headers/authorization.py"
    click BaseHeader "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/headers/header.py"
    click MethodEnum "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/method.py"
    click RequestModel "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/objects/request.py"
    click ResponseModel "https://github.com/jeandemeusy/api-lib/blob/master/src/api_lib/objects/response.py"

    %% Styles
    classDef coreLib fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
```
