How hubspot/hubspot-public-api-spec-collection works
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”)