generated from coulomb/repo-seed
77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
# API v2 Compatibility Spec
|
|
|
|
## Purpose
|
|
|
|
Core Hub must preserve the Inter-Hub API surfaces that existing consumers rely on until each consumer has moved to a new explicit Core Hub contract.
|
|
|
|
## Current Compatibility Semantics
|
|
|
|
The active ops-hub gate expects unauthenticated `GET /api/v2/hubs` to return `401`, not `404` or public data. Core Hub therefore treats hub registry and bootstrap resources as protected, while keeping static catalogs and API documentation public.
|
|
|
|
The OpenAPI document served at `/api/v2/openapi.json` includes both FastAPI-native `/api/v2/...` paths and Inter-Hub-compatible unprefixed aliases such as `/hubs`, `/hub-capability-manifests`, `/api-consumers`, and `/policy-scopes`.
|
|
|
|
## Public Catalog/Documentation Surfaces
|
|
|
|
- `GET /api/v2/widget-types`
|
|
- `GET /api/v2/event-types`
|
|
- `GET /api/v2/annotation-categories`
|
|
- `GET /api/v2/policy-scopes`
|
|
- `GET /api/v2/openapi.json`
|
|
- `GET /api/v2/openapi.yaml`
|
|
- `GET /api/v2/docs`
|
|
|
|
## Protected Bootstrap Surfaces
|
|
|
|
- `GET /api/v2/hubs`
|
|
- `POST /api/v2/hubs`
|
|
- `GET /api/v2/hub-capability-manifests`
|
|
- `POST /api/v2/hub-capability-manifests`
|
|
- `PATCH /api/v2/hub-capability-manifests/{manifest_id}`
|
|
- `POST /api/v2/hub-capability-manifests/{manifest_id}/activate`
|
|
- `GET /api/v2/api-consumers`
|
|
- `POST /api/v2/api-consumers`
|
|
- `POST /api/v2/api-consumers/{consumer_id}/api-keys`
|
|
- `GET /api/v2/widgets`
|
|
- `POST /api/v2/widgets`
|
|
- `GET /api/v2/interaction-events`
|
|
- `POST /api/v2/interaction-events`
|
|
- `GET /api/v2/hub-registry`
|
|
- `POST /api/v2/token`
|
|
|
|
Deferred protected surfaces currently return empty compatibility collections:
|
|
|
|
- `/api/v2/annotations`
|
|
- `/api/v2/requirement-candidates`
|
|
- `/api/v2/decision-records`
|
|
- `/api/v2/deployment-records`
|
|
- `/api/v2/outcome-signals`
|
|
|
|
## Known Consumers
|
|
|
|
- `ops-hub` bootstrap and Inter-Hub gate probes
|
|
- `activity-core` optional Inter-Hub sink
|
|
- Custodian workplans and operator smokes
|
|
- Downstream docs or probes that check the hub registry
|
|
|
|
## Acceptance Standard
|
|
|
|
A route is compatible when:
|
|
|
|
- method and path match;
|
|
- auth behavior matches public/protected expectations;
|
|
- success status and response shape satisfy captured fixtures;
|
|
- error shape is documented;
|
|
- at least one consumer smoke passes against Core Hub.
|
|
|
|
## Current Evidence
|
|
|
|
2026-06-27 local evidence:
|
|
|
|
- `ops-hub/scripts/interhub-gate-probe.py --base http://127.0.0.1:8017` passed.
|
|
- `ops-hub/scripts/ops-hub-bootstrap-api.py` passed against local Core Hub with a throwaway operator token.
|
|
- The bootstrap created an ops-hub record, activated manifest, API consumer, runtime API key, 14 widgets, and one `ops-endpoint-verified` event.
|
|
|
|
## Transition Rule
|
|
|
|
Do not remove an Inter-Hub-compatible route until every known consumer either passes against the new Core Hub-native route or has a recorded cancellation decision.
|