{"id":36753833,"url":"https://github.com/openshift-hyperfleet/hyperfleet-api-spec","last_synced_at":"2026-05-11T11:08:03.335Z","repository":{"id":322412727,"uuid":"1089359001","full_name":"openshift-hyperfleet/hyperfleet-api-spec","owner":"openshift-hyperfleet","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-17T13:19:46.000Z","size":206,"stargazers_count":0,"open_issues_count":1,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T18:54:53.539Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeSpec","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openshift-hyperfleet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T08:33:24.000Z","updated_at":"2025-12-17T13:19:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openshift-hyperfleet/hyperfleet-api-spec","commit_stats":null,"previous_names":["openshift-hyperfleet/hyperfleet-api-spec"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/openshift-hyperfleet/hyperfleet-api-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openshift-hyperfleet","download_url":"https://codeload.github.com/openshift-hyperfleet/hyperfleet-api-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift-hyperfleet%2Fhyperfleet-api-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T12:47:41.852Z","updated_at":"2026-05-11T11:08:03.325Z","avatar_url":"https://github.com/openshift-hyperfleet.png","language":"TypeSpec","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperFleet OpenAPI spec\n\nThis repository supports the development of the Hyperfleet OpenAPI contract, but is not the source-of-truth for the OpenAPI contract.\n\nThis project hosts the TypeSpec files to generate the HyperFleet OpenAPI specifications. Typescpec is an implementation detail providing better ergonomics than writing contracts in plain YAML, specially when dealing with contract variants that we need to keep aligned. The repository is organized to support multiple service variants (core, GCP, etc.) while sharing common models and interfaces.\n\nAccess to the OpenAPI contract source of truth in hyperfleet-api repository:\n\n- \u003chttps://openshift-hyperfleet.github.io/hyperfleet-api-spec/index.html\u003e\n\nAccess directly to the latest generated contract in this repository:\n\n- core: \u003chttps://openshift-hyperfleet.github.io/hyperfleet-api-spec/core.html\u003e\n- GCP: \u003chttps://openshift-hyperfleet.github.io/hyperfleet-api-spec/gcp.html\u003e\n\n## Consuming the API Specifications\n\n### Source of truth (Production contract)\n\nThe OpenAPI contract that gets promoted to production is the one at:\n\n- \u003chttps://raw.githubusercontent.com/openshift-hyperfleet/hyperfleet-api/refs/heads/main/openapi/openapi.yaml\u003e\n\n**Download examples**:\n\n```bash\ncurl -L -O https://github.com/openshift-hyperfleet/hyperfleet-api/releases/latest/download/openapi.yaml\n\n```\n\n### Latest Releases (Recommended for development)\n\nDownload the latest stable OpenAPI specifications directly from GitHub Releases:\n\n**Direct URLs** (always get the latest stable version):\n\n- Core: `https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/latest/download/core-openapi.yaml`\n- GCP: `https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/latest/download/gcp-openapi.yaml`\n\n**Download examples**:\n\n```bash\n# Core API\ncurl -L -O https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/latest/download/core-openapi.yaml\n\n# GCP API\ncurl -L -O https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/latest/download/gcp-openapi.yaml\n```\n\n**Use in code generation** (always uses latest stable version):\n\n```bash\n# Generate Go client from Core API\nopenapi-generator generate -i https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/latest/download/core-openapi.yaml -g go -o ./client\n\n# Generate Python client from GCP API\nopenapi-generator generate -i https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/latest/download/gcp-openapi.yaml -g python -o ./client\n```\n\n### Version-Specific Downloads\n\nTo download a specific version (e.g., v1.0.0):\n\n```bash\n# Core API\ncurl -L -O https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/download/v1.0.0/core-openapi.yaml\n\n# GCP API\ncurl -L -O https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/download/v1.0.0/gcp-openapi.yaml\n```\n\n**See all releases**: \u003chttps://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases\u003e\n\n## Repository Structure\n\nThe repository is organized with root-level configuration files and three main directories:\n\n### Root-Level Files\n\n- **`main.tsp`** - Main TypeSpec entry point that imports all service definitions\n- **`aliases.tsp`** - Provider alias configuration file (re-linked to switch between providers)\n- **`aliases-core.tsp`** - Core provider aliases (defines `ClusterSpec` as `CoreClusterSpec` which is `Record\u003cunknown\u003e`)\n- **`aliases-gcp.tsp`** - GCP provider aliases (defines `ClusterSpec` as `GCPClusterSpec`)\n- **`tspconfig.yaml`** - TypeSpec compiler configuration\n\n### `/models`\n\nContains shared models used by all service variants:\n\n- **`models/clusters/`** - Cluster resource definitions (interfaces and base models)\n- **`models/statuses/`** - Status resource definitions for clusters and nodepools\n- **`models/nodepools/`** - NodePool resource definitions\n- **`models/common/`** - Common models and types (APIResource, Error, QueryParams, etc.)\n\n### `/models-core`\n\nContains core provider-specific model definitions:\n\n- **`models-core/cluster/model.tsp`** - Defines `CoreClusterSpec` as `Record\u003cunknown\u003e` (generic)\n\n### `/models-gcp`\n\nContains GCP provider-specific model definitions:\n\n- **`models-gcp/cluster/model.tsp`** - Defines `GCPClusterSpec` with GCP-specific properties\n\n### `/services`\n\nContains service definitions that generate the OpenAPI specifications:\n\n- **`services/clusters.tsp`** - Cluster resource endpoints\n- **`services/statuses.tsp`** - Status resource endpoints (GET only - public API)\n- **`services/statuses-internal.tsp`** - Status write endpoints (POST/PUT - internal API, see below)\n- **`services/nodepools.tsp`** - NodePool resource endpoints\n\n#### Public vs Internal API Split\n\nThe status endpoints are split into two files to support different API consumers:\n\n| File | Operations | Audience | Included in Build |\n|------|------------|----------|-------------------|\n| `statuses.tsp` | GET (read) | External clients | ✅ Yes (default) |\n| `statuses-internal.tsp` | POST (write) | Internal adapters | ❌ No (opt-in) |\n| `statuses-internal.tsp` | PUT (write) | Internal adapters | ❌ No (opt-in) |\n\n**Why the split?**\n\n- **External clients** (UI, CLI, monitoring) only need to read status information\n- **Internal adapters** (validator, provisioner, dns) need to write/update status reports\n- Separating these allows generating different API contracts for different audiences\n\n## Prerequisites\n\nAfter cloning the repository, install all dependencies:\n\n```bash\nnpm install\n```\n\nThis installs the TypeSpec compiler and all required libraries into `node_modules/`. The build scripts invoke `tsp` directly from `node_modules/.bin/`, so no global install is needed.\n\n## Building OpenAPI Specifications\n\nThe repository uses a single `main.tsp` entry point. To generate either the core API or GCP API, you need to re-link the `aliases.tsp` file to point to the desired provider aliases file.\n\n### Output Formats\n\nThe build system supports two OpenAPI formats:\n\n- **OpenAPI 3.0** (default) - Modern format with full feature support\n- **OpenAPI 2.0 (Swagger)** - Legacy format for compatibility with older tools\n\n### Using npm Scripts (Recommended)\n\nThe easiest way to build the OpenAPI schema is using the provided npm scripts:\n\n```bash\n# Build OpenAPI 3.0 only\nnpm run build:core       # Build Core API (OpenAPI 3.0)\nnpm run build:gcp        # Build GCP API (OpenAPI 3.0)\n\n# Build both OpenAPI 3.0 and OpenAPI 2.0 (Swagger)\nnpm run build:core:swagger   # Build Core API with Swagger\nnpm run build:gcp:swagger    # Build GCP API with Swagger\n\n# Build all providers with both formats\nnpm run build:all\n```\n\n### Using the Build Script Directly\n\nYou can also use the `build-schema.sh` script directly:\n\n```bash\n# Build OpenAPI 3.0 only\n./build-schema.sh core\n./build-schema.sh gcp\n\n# Build with OpenAPI 2.0 (Swagger) output\n./build-schema.sh core --swagger\n./build-schema.sh gcp --swagger\n# or use the alias:\n./build-schema.sh gcp --openapi2\n```\n\nThe script automatically:\n\n1. Validates the provider parameter\n2. Re-links `aliases.tsp` to the appropriate provider aliases file\n3. Compiles the TypeSpec to generate the OpenAPI 3.0 schema\n4. (If `--swagger` flag is used) Converts OpenAPI 3.0 to OpenAPI 2.0 (Swagger)\n5. Outputs the results to `schemas/{provider}/`:\n   - `openapi.yaml` - OpenAPI 3.0 specification\n   - `swagger.yaml` - OpenAPI 2.0 (Swagger) specification (if `--swagger` flag is used)\n\n**Extending to new providers**: Simply create `aliases-{provider}.tsp` and the script will automatically detect and support it.\n\n### Manual Build (Alternative)\n\nIf you prefer to build manually:\n\n#### Build Core API\n\n1. Re-link `aliases.tsp` to `aliases-core.tsp`:\n\n   ```bash\n   ln -sf aliases-core.tsp aliases.tsp\n   ```\n\n2. Compile the TypeSpec:\n\n   ```bash\n   tsp compile main.tsp\n   ```\n\n   Output: `tsp-output/schema/openapi.yaml`\n\n3. (Optional) Convert to OpenAPI 2.0 (Swagger):\n\n   ```bash\n   npx api-spec-converter --from=openapi_3 --to=swagger_2 --syntax=yaml \\\n     tsp-output/schema/openapi.yaml \u003e tsp-output/schema/swagger.yaml\n   ```\n\n#### Build GCP API\n\n1. Re-link `aliases.tsp` to `aliases-gcp.tsp`:\n\n   ```bash\n   ln -sf aliases-gcp.tsp aliases.tsp\n   ```\n\n2. Compile the TypeSpec:\n\n   ```bash\n   tsp compile main.tsp\n   ```\n\n   Output: `tsp-output/schema/openapi.yaml`\n\n3. (Optional) Convert to OpenAPI 2.0 (Swagger):\n\n   ```bash\n   npx api-spec-converter --from=openapi_3 --to=swagger_2 --syntax=yaml \\\n     tsp-output/schema/openapi.yaml \u003e tsp-output/schema/swagger.yaml\n   ```\n\n**Note**: The `aliases.tsp` file controls which provider-specific `ClusterSpec` definition is used throughout the service definitions. By re-linking it to either `aliases-core.tsp` or `aliases-gcp.tsp`, you switch between the generic `Record\u003cunknown\u003e` spec and the GCP-specific `GCPClusterSpec`.\n\n## Architecture\n\nThe HyperFleet API provides simple CRUD operations for managing cluster resources and their status history:\n\n- **Simple CRUD only**: No business logic, no event creation\n- **Separation of concerns**: API layer focuses on data persistence; orchestration logic is handled by external components\n\n## Adding a New Provider\n\nTo add a new provider (e.g., AWS):\n\n1. Create provider model directory: `models-aws/cluster/model.tsp`\n\n   ```typescript\n   model AWSClusterSpec {\n     awsProperty1: string;\n     awsProperty2: string;\n   }\n   ```\n\n2. Create provider aliases file: `aliases-aws.tsp`\n\n   ```typescript\n   import \"./models-aws/cluster/model.tsp\";\n   alias ClusterSpec = AWSClusterSpec;\n   ```\n\n3. To generate the AWS API, re-link `aliases.tsp`:\n\n   ```bash\n   ln -sf aliases-aws.tsp aliases.tsp\n   tsp compile main.tsp\n   ```\n\n## Adding a New Service\n\nTo add a new service (e.g., with additional endpoints):\n\n1. Create a new service file: `services/new-service.tsp`\n\n   ```typescript\n   import \"@typespec/http\";\n   import \"@typespec/openapi\";\n   import \"../models/common/model.tsp\";\n   // ... other imports as needed\n   \n   namespace HyperFleet;\n   @route(\"/new-resource\")\n   interface NewService {\n     // ... endpoint definitions\n   }\n   ```\n\n2. Import the new service in `main.tsp`:\n\n   ```typescript\n   import \"./services/new-service.tsp\";\n   ```\n\n## Dependencies\n\n- `@typespec/compiler` - TypeSpec compiler\n- `@typespec/http` - HTTP protocol support\n- `@typespec/openapi` - OpenAPI decorators\n- `@typespec/openapi3` - OpenAPI 3.0 emitter\n- `api-spec-converter` - Converts OpenAPI 3.0 to OpenAPI 2.0 (Swagger)\n\n## Updating the Specification\n\n### Making an API change\n\n1. **Edit the TypeSpec sources** in `models/`, `models-gcp/`, or `services/`.\n\n2. **Bump the version** in `main.tsp`:\n\n   ```typescript\n   @info(#{ version: \"1.0.12\", ... })\n   ```\n\n3. **Rebuild all four schemas**:\n\n   ```bash\n   ./build-schema.sh core\n   ./build-schema.sh core --swagger\n   ./build-schema.sh gcp\n   ./build-schema.sh gcp --swagger\n   ```\n\n4. **Update [CHANGELOG.md](CHANGELOG.md)** — move your changes from `[Unreleased]` into a new versioned entry.\n\n5. **Open a PR.** CI enforces three things automatically:\n   - Committed schemas match freshly generated output (catches manual edits or forgotten rebuilds).\n   - OpenAPI 3.0 schemas pass `spectral:oas` linting.\n   - Version in `main.tsp` is higher than the latest GitHub release tag.\n\n6. **Merge to main.** The release workflow runs automatically: it creates an annotated tag (`vX.Y.Z`), builds all four schemas from scratch, and publishes a GitHub release with the artifacts attached.\n\n### Consuming schemas as a Go module\n\nEach release tag is a valid Go module version. Import the embedded schemas:\n\n```go\nimport specschemas \"github.com/openshift-hyperfleet/hyperfleet-api-spec/schemas\"\n\ndata, err := specschemas.FS.ReadFile(\"gcp/openapi.yaml\")\n```\n\nTo update a consumer after a new release:\n\n```bash\ngo get github.com/openshift-hyperfleet/hyperfleet-api-spec@v1.0.12\n```\n\nTo test locally against an unreleased branch, use a `replace` directive in your `go.mod`:\n\n```go\nreplace github.com/openshift-hyperfleet/hyperfleet-api-spec =\u003e /path/to/local/hyperfleet-api-spec\n```\n\nSee [hyperfleet-api docs/openapi-spec.md](https://github.com/openshift-hyperfleet/hyperfleet-api/blob/main/docs/openapi-spec.md) for how the hyperfleet-api service consumes this module.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n\n- Development setup and workflow\n- Repository structure details\n- Testing guidelines\n- Commit standards\n- Pull request process\n\n## Developing with the Visual Studio Typespec extension\n\nThe repository works with different contracts (core and GCP) but a single Typespec `main.tsp`.\nThis is accomplished by maintaining an `aliases.tsp` file that holds the \"active\" concrete types to use (core or GCP).\n\n- When working on the core API, the `aliases.tsp` points to `aliases-core.tsp`\n- When working on the GCP API, the `aliases.tsp` points to `aliases-gcp.tsp`\n\nThe downside of this is that it confuses the Typespec extension:\n\n- For the \"non-active\" type files, the plugin may show errors as not defined types\n- Since we duplicate aliases, the plugin may display an error of a type being duplicated\n\nBut, both the `build-schema.sh` script using the `tsp` CLI command as the plugin option to \"Emit from Typespec\" work fine.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift-hyperfleet%2Fhyperfleet-api-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenshift-hyperfleet%2Fhyperfleet-api-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift-hyperfleet%2Fhyperfleet-api-spec/lists"}