# hubspot/hubspot-api-python architecture

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

- Interactive diagram: https://gitdiagram.com/hubspot/hubspot-api-python
- Repository: https://github.com/hubspot/hubspot-api-python

## Overview

##### Project Type and Purpose
- This is a Python SDK (client library) for interacting with the HubSpot REST APIs (v3).
- It is *not* a full-stack web app but a standalone library that provides a convenient interface (models, API classes, configuration, helpers) to send HTTP requests to HubSpot’s servers.

##### High-Level Architecture
- External Systems:
- HubSpot REST API endpoints (the cloud service)
- Underlying HTTP client (urllib3 via swagger-generated API client)
- Core Library Layers:
1. **Client Layer**
– HubSpot class (hubspot/client.py)
– Factory methods (HubSpot.create, configuring access_token, hapikey support deprecated)
2. **Configuration & Transport**
– `configuration.py` modules in each subpackage
– `api_client.py` (shared HTTP client, retry middleware support)
– Request builder (`utils/requests/http_request_builder.py`)
– HTTP auth (`utils/requests/http_auth.py`)
3. **API Packages**
– One package per API group (e.g., crm/contacts, cms/blogs, marketing/emails, oauth, webhooks)
– Each has:
- `api/*.py`: entry points for operations (basic_api.py, batch_api.py, etc.)
- `models/*.py`: data classes for requests/responses
- `exceptions.py`: APIException classes
- `rest.py`: low-level REST call wrappers
4. **Discovery Module**
– `discovery/`: dynamically fetch metadata/endpoints from HubSpot (used for code generation or advanced use)
5. **Utilities**
– OAuth URL builder (`utils/oauth.py`)
– Signature validator (`utils/signature.py`)
– Generic object helpers (`utils/objects.py`)
- Test Suite
– `tests/`: integration tests (against real HubSpot if credentials provided) and spec tests (mocked).

##### Components and Interactions
a. **User Application**
– Imports and configures `HubSpot` client
– Invokes high-level methods (e.g., `client.crm.contacts.basic_api.create(...)`)
b. **HubSpot SDK (your library)**
– **Client Layer** routes calls to the correct API package
– **Configuration & Transport** builds HTTP requests, applies auth (OAuth token or hapikey), retry policies
– **API Packages** serialize method parameters into request bodies/URL params, call low-level `rest.py`
– **Models** parse JSON responses into Python objects with `to_dict` support
– **Exceptions** thrown on non-2xx responses
– **Discovery** can dynamically introspect or generate calls for unwrapped endpoints
– **Utilities** provide helper functions around OAuth/URL signing
c. **HTTP Client**
– urllib3 (via generated swagger client) sends HTTP(S) requests to HubSpot’s servers
– Receives HTTP responses
d. **HubSpot REST API**
– The external service fulfilling API calls

##### Architectural Patterns and Principles
- **Layered Architecture**: clear separation between client interface, transport, API definitions, and models
- **Code Generation**: each API package follows a consistent pattern (api / models / rest) generated from OpenAPI definitions
- **Dependency Injection**: retry, auth, and base URL configurable via `configuration.py`
- **Single Responsibility**: each module has a focused role (e.g., basic_api only handles “basic” operations)

##### Capturing Essential Elements
- Be detailed: show each logical layer and its modules.
- Don’t over-partition: group similar API packages together (e.g., all `hubspot.crm.*` under one zone).
– Core SDK code
– Utility helpers
– External systems (HubSpot API, HTTP client)
– Tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application
    Application["User Application"]:::app

    %% Client Layer
    subgraph "Client Layer"
        Client["HubSpot Client"]:::clientLayer
    end

    %% Configuration & Transport
    subgraph "Configuration & Transport"
        HTTPRequestBuilder["HTTP Request Builder"]:::config
        HTTPAuth["HTTP Auth"]:::config
        ConfigCRMContacts["Config Module (CRM Contacts)"]:::config
        ConfigOAuth["Config Module (OAuth)"]:::config
        APIClientCRM["API Client (CRM Contacts)"]:::config
    end

    %% API Packages
    subgraph "API Packages"
        subgraph "CRM Contacts Package"
            BasicAPI["basic_api"]:::apiPkg
            BatchAPI["batch_api"]:::apiPkg
            SearchAPI["search_api"]:::apiPkg
            ModelsSPO["simple_public_object"]:::models
            Exceptions["exceptions"]:::exceptions
            RestWrapper["rest"]:::rest
        end
    end

    %% Discovery Module
    subgraph "Discovery"
        DiscoveryBase["Discovery Base"]:::discovery
        DiscoveryCRMContacts["Discovery CRM Contacts"]:::discovery
    end

    %% Utilities
    subgraph "Utilities"
        OAuthUtils["OAuth URL Builder"]:::utils
        SignatureUtils["Signature Validator"]:::utils
        ObjectsUtils["Generic Object Helpers"]:::utils
    end

    %% External Systems
    HTTPClient["HTTP Client\n(urllib3 via swagger)"]:::external
    HubSpotService["HubSpot REST API"]:::external

    %% Test Suite
    subgraph "Tests"
        IntegrationContacts["test_contacts.py"]:::test
        IntegrationWebhooks["test_webhooks.py"]:::test
        SpecRequestBuilder["test_request_builder.py"]:::test
        SpecAuth["test_auth.py"]:::test
    end

    %% Data Flow - Requests
    Application -->|"uses"| Client
    Client -->|"routes to"| BasicAPI
    BasicAPI -->|"calls"| RestWrapper
    RestWrapper -->|"builds request"| HTTPRequestBuilder
    RestWrapper -->|"applies auth"| HTTPAuth
    HTTPRequestBuilder -->|"sends via"| HTTPClient
    HTTPAuth -->|"injects creds"| HTTPClient
    HTTPClient -->|"HTTP(S) request"| HubSpotService

    %% Data Flow - Responses
    HubSpotService -->|"HTTP response"| HTTPClient
    HTTPClient -->|"returns to"| RestWrapper
    RestWrapper -->|"parses response"| BasicAPI
    BasicAPI -->|"returns model"| Application

    %% Configuration Usage
    Client -->|"injects config"| ConfigCRMContacts
    Client -->|"injects config"| ConfigOAuth
    BasicAPI -->|"uses client"| APIClientCRM

    %% Discovery Flow
    Client -->|"can use"| DiscoveryBase
    DiscoveryBase -->|"fetches metadata"| DiscoveryCRMContacts

    %% Utilities Usage
    Client -->|"may use"| OAuthUtils
    RestWrapper -->|"may use"| SignatureUtils
    BasicAPI -->|"uses helpers"| ObjectsUtils

    %% Tests invoking SDK
    IntegrationContacts -->|"integration test"| Client
    IntegrationWebhooks -->|"integration test"| Client
    SpecRequestBuilder -->|"unit test"| HTTPRequestBuilder
    SpecAuth -->|"unit test"| HTTPAuth

    %% Click Events
    click Client "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/client.py"
    click HTTPRequestBuilder "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/utils/requests/http_request_builder.py"
    click HTTPAuth "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/utils/requests/http_auth.py"
    click ConfigCRMContacts "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/configuration.py"
    click ConfigOAuth "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/oauth/configuration.py"
    click APIClientCRM "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/api_client.py"
    click BasicAPI "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/api/basic_api.py"
    click BatchAPI "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/api/batch_api.py"
    click SearchAPI "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/api/search_api.py"
    click ModelsSPO "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/models/simple_public_object.py"
    click Exceptions "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/exceptions.py"
    click RestWrapper "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/crm/contacts/rest.py"
    click DiscoveryBase "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/discovery/discovery_base.py"
    click DiscoveryCRMContacts "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/discovery/crm/contacts/discovery.py"
    click OAuthUtils "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/utils/oauth.py"
    click SignatureUtils "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/utils/signature.py"
    click ObjectsUtils "https://github.com/hubspot/hubspot-api-python/blob/master/hubspot/utils/objects.py"
    click IntegrationContacts "https://github.com/hubspot/hubspot-api-python/blob/master/tests/integration/test_contacts.py"
    click IntegrationWebhooks "https://github.com/hubspot/hubspot-api-python/blob/master/tests/integration/test_webhooks.py"
    click SpecRequestBuilder "https://github.com/hubspot/hubspot-api-python/blob/master/tests/spec/utils/requests/test_request_builder.py"
    click SpecAuth "https://github.com/hubspot/hubspot-api-python/blob/master/tests/spec/utils/requests/test_auth.py"

    %% Styles
    classDef app fill:#E3F2FD,stroke:#0D47A1,stroke-width:1px
    classDef clientLayer fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef config fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px
    classDef apiPkg fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px
    classDef models fill:#FCE4EC,stroke:#AD1457,stroke-width:1px
    classDef exceptions fill:#FFEBEE,stroke:#C62828,stroke-width:1px
    classDef rest fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef discovery fill:#E8EAF6,stroke:#283593,stroke-width:1px
    classDef utils fill:#EDE7F6,stroke:#4527A0,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#37474F,stroke-width:1px,stroke-dasharray: 5 5
    classDef test fill:#F1F8E9,stroke:#689F38,stroke-width:1px,stroke-dasharray: 2 2
```
