Skip to content

README.md

Latest commit

 

History

History
102 lines (69 loc) · 3.15 KB

README.md

File metadata and controls

102 lines (69 loc) · 3.15 KB

stackql-provider-heroku

This repository contains the tooling, code, and CI to build and test a StackQL provider for the Heroku Platform API. It leverages the official Heroku API JSON Schema to generate OpenAPI-compatible service specifications with custom x-stackQL-* extensions.

📦 What this Repo Does

  • Fetches the Heroku Platform API schema
  • Converts the schema into modular OpenAPI 3.0 service specs
  • Annotates each OpenAPI operation and schema with x-stackQL-* extensions
  • Outputs a full StackQL provider manifest and service spec tree
  • Includes CI tests to validate generated specs and example queries

📥 Getting the Heroku Platform API Schema

The Heroku Platform API is described using a machine-readable JSON schema hosted in GitHub.

Step 1: Clone the Schema Repo

git clone https://github.com/heroku/platform-api-schema.git
cd platform-api-schema

This will provide access to the raw schema in:

schema-v3.json

Step 2: Inspect the Schema

You can view schema-v3.json to see the top-level definitions. It's structured similarly to JSON Hyper-Schema with links, href, and rel describing endpoints and methods.

🔄 Convert Schema to StackQL-Compatible OpenAPI Specs

To convert this schema into StackQL-compatible service specs:

  1. Use or build a Python/Node.js script to:

    • Parse each top-level Heroku resource (e.g., app, addon, release)
    • Convert each href and method into an OpenAPI path + operation
    • Extract request and response bodies into components
    • Add x-stackQL-resource, x-stackQL-method, and x-stackQL-verb to each operation

  2. Group operations by service (e.g., apps, addons, builds) and output them to:

    provider/
└── heroku/
    └── v0/
        └── services/
            ├── apps.yaml
            ├── addons.yaml
            └── builds.yaml

  3. Generate a top-level provider manifest:

    name: heroku
version: v0
services:
  - name: apps
    file: services/apps.yaml
  - name: addons
    file: services/addons.yaml
  # ...

🚧 Work in Progress

This repo is under active development. Planned work includes:

  • JSON Schema → OpenAPI transformer
  • StackQL extensions injector
  • GitHub Actions CI for schema validation
  • Unit tests for provider coverage
  • Documentation and query examples

📚 References

👷‍♂️ Contributing

Contributions are welcome! Feel free to open issues, PRs, or feature suggestions.