# hubspot/hubspot-public-api-spec-collection architecture

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

- Interactive diagram: https://gitdiagram.com/hubspot/hubspot-public-api-spec-collection
- Repository: https://github.com/hubspot/hubspot-public-api-spec-collection

## Overview

##### Project Type & Purpose
- This repository is not a running application but a specification‐management tool: it stores HubSpot’s public APIs as OpenAPI 3.0 schemas (under PublicApiSpecs/) and related Postman collection definitions (in .postman/).
- Its sole purpose is to keep HubSpot’s Postman workspace in sync with the latest API schemas so internal teams always have up-to-date collections.

##### Key Architectural Components
a. Source Repository (GitHub or internal SCM)
- Stores OpenAPI 3.0 JSON schemas (PublicApiSpecs/…)
- Stores Postman collection definitions (.postman/api_*.json)
b. CI/CD Pipeline (e.g., GitHub Actions, Jenkins)
- Watches repo for commits to API specs or .postman folder
- Runs validation (e.g., lint OpenAPI schemas)
- Executes generation scripts
c. Generation & Sync Tooling
- Scripts or a Postman CLI tool that:
- Reads OpenAPI schemas
- Transforms them into Postman collections
- Validates collection format
- Pushes via Postman API
d. External Service: Postman Platform
- Postman REST API endpoint for updating collections
- HubSpot Public API Workspace where collections live
e. Stakeholders
- API Tooling Team (maintains scripts)
- API Developers (update schemas)

##### Component Interactions & Data Flow
1. Developer Push →
- New or updated JSON schema in PublicApiSpecs/ or .postman/
2. CI Trigger →
- Validate schema →
- Run “generate‐collection” script
3. Generation Script →
- Converts schema → Postman collection JSON
- Calls Postman REST API (Auth token)
4. Postman API →
- Overwrites or creates collections in HubSpot Public API Workspace
5. Consumers →
- Internal API developers open Postman → see updated collections

##### Architectural Patterns & Principles
- API-First: OpenAPI schemas are the source of truth
- Infrastructure as Code: Postman definitions live in source control
- CI/CD Automation: Ensures zero-touch sync after every change
- Separation of Concerns:
- Schema storage (PublicApiSpecs/)
- Presentation (Postman collections)
- Orchestration (CI/CD + scripts)

##### Must-Include
- Clear labels on all components (e.g., “GitHub Repo,” “CI/CD Runner,” “Postman REST API”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    Developer["API Developers"]:::user
    ToolingTeam["API Tooling Team"]:::user

    %% Source Repository
    subgraph "Source Repository"
        Repo["GitHub Repo"]:::file
        Specs["OpenAPI Schema Storage\nPublicApiSpecs/"]:::file
        Collections["Postman Collection Definitions\n.postman/api/"]:::file
        Guide["Documentation / Usage Guide\nREADME.md"]:::file
    end

    %% CI/CD and Scripts
    CI["CI/CD Runner"]:::process
    Script["Generate-Collection Script"]:::process

    %% External Services
    PostmanAPI["Postman REST API"]:::service
    PostmanWS["HubSpot Public API Workspace"]:::service

    %% Flows
    Developer -->|"Push Change"| Repo
    Repo -->|"Contains specs"| Specs
    Repo -->|"Contains collections"| Collections
    Repo -->|"Contains docs"| Guide

    Repo -->|"Trigger Commit"| CI
    CI -->|"Lint & Validate"| Specs
    CI -->|"Lint & Validate"| Collections
    CI -->|"Run generate-collection"| Script

    Script -->|"Convert OpenAPI → Postman Collection"| CollectionsGenerated["Postman Collection JSON"]:::process
    CollectionsGenerated -->|"Push via REST API"| PostmanAPI
    PostmanAPI -->|"Update Collections"| PostmanWS
    Developer -->|"View Collections"| PostmanWS

    %% Click Events
    click Specs "https://github.com/hubspot/hubspot-public-api-spec-collection/tree/main/PublicApiSpecs/"
    click Collections "https://github.com/hubspot/hubspot-public-api-spec-collection/tree/main/.postman/api/"
    click Repo "https://github.com/hubspot/hubspot-public-api-spec-collection/blob/main/."
    click Guide "https://github.com/hubspot/hubspot-public-api-spec-collection/blob/main/README.md"

    %% Styles
    classDef file fill:#cce5ff,stroke:#004085,color:#004085;
    classDef process fill:#fff3cd,stroke:#856404,color:#856404;
    classDef service fill:#d4edda,stroke:#155724,color:#155724;
    classDef user fill:#f8d7da,stroke:#721c24,color:#721c24;
```
