Skip to content

API Schema Reference Catalog

What is this?

A curated, versioned index of the API schemas Bluefly actually depends on, plus pinned reference copies of the external ones. It sits between the real authorities (vendor docs, or the producing Bluefly repo) and the consumers (agents, api_normalization, Tool API, MCP, tests).

UPSTREAM API PROVIDER (GitLab, Raindrop, Acquia, ...)
        |
CURATED / PINNED REFERENCE COPY   <- you are here (external/)
Engineering-Standard/reference/api-schemas/
        |
api-schema-registry
validation / aggregation / discovery / publication (that repo's own job)
        |
agents, Drupal api_normalization, Tool API, MCP, testing

For a Bluefly-owned API, the producing repository stays source authority. This catalog does not fork a second copy of it — it holds a bluefly/<service>/metadata.yaml pointer instead (see bluefly/api-schema-registry/metadata.yaml).

What belongs here

  • external/<provider>/<api-family>/<version>/ — a pinned copy of a stable, vendor-published OpenAPI/Swagger document, plus a metadata.yaml recording exactly where it came from, when, and its sha256. Two providers are curated today: GitLab REST API and the Raindrop Query API. See catalog.yaml.
  • bluefly/<service>/metadata.yaml — a pointer/classification record for a Bluefly-owned or Bluefly-generated artifact whose real bytes live somewhere else (almost always api-schema-registry). No spec content is duplicated here.

What does NOT belong here

  • A rendered Swagger UI / Redoc / Scalar HTML docs page. That is not a schema. If a provider only publishes rendered docs and no machine-readable file, the metadata records SCHEMA_AVAILABLE: NO and the discovery details — nothing is fabricated.
  • A site/tenant-specific generated JSON:API document (e.g. one Acquia Source instance's content-model auto-doc). That is an INSTANCE/content-model-specific artifact, not a timeless vendor schema — see bluefly/acquia-source-instance/metadata.yaml for why it is classified out rather than pinned as an "Acquia" schema.
  • Every Bluefly service spec that already lives in api-schema-registry. That repo is the registry-of-record for Bluefly's own ~65 service contracts (openapi/<service>/openapi.yaml each); duplicating them here would create a second writable authority for the same artifact, which this catalog exists to avoid, not create.
  • Anything containing a live API key, OAuth/bearer token, cookie, client secret, or private tenant credential. Every downloaded document is inspected for accidental credentials before being committed; none were found in the two pinned specs added here.

How do I add a schema?

  1. Locate the real machine-readable OpenAPI/Swagger document (not the docs page it's rendered from).
  2. Download it, and record sha256, fetched_at, upstream_url (and upstream_repository / upstream_ref / upstream_commit when the source is a git repo, e.g. GitLab's own spec).
  3. Validate it — this repo's convention is @redocly/cli lint (the same validator api-schema-registry uses); record FILE_PARSE, errors, and warnings in the validation: block of the metadata.
  4. Place the file under external/<provider>/<api-family>/<version>/ with a sibling metadata.yaml following the contract below.
  5. Add a row to catalog.yaml.
  6. If the schema is genuinely Bluefly-produced, it does NOT go under external/ — put a pointer metadata.yaml under bluefly/<service>/ instead and leave the real spec in its producing repo (or in api-schema-registry if that repo already owns it).

How do I refresh one?

Re-fetch from the recorded upstream_url (or upstream_repository at upstream_ref), compare sha256: - unchanged -> no update needed. - changed -> re-validate, update the pinned file, update sha256/fetched_at/upstream_commit, note anything breaking, open an MR. Nothing is mutated silently outside of git review — there is no cron/refresh script here yet; api-schema-registry does not currently expose a URL-registration or refresh command either (its CLI has sync-down for pushing FROM the registry INTO a consumer, not for pulling an external URL IN). If/when it gains one, prefer it over this manual loop.

How do I register one?

For an external vendor schema: there is nothing further to "register" beyond the steps above — this catalog IS the registration record (pinned copy + provenance + validation result).

For a Bluefly-owned schema: register it in api-schema-registry itself, its actual home: add openapi/<service>/openapi.yaml there, then run its documented workflow — validate -> aggregate -> control-plane -> repository-metadata -> endpoints-index (see bluefly/api-schema-registry/metadata.yaml for the exact CLI commands, confirmed against api-schema-registry --help on release/v0.1.x, v1.5.4).

How do I find one?

  • Looking for a stable, external, third-party schema Bluefly consumes? Check external/ and catalog.yaml here first.
  • Looking for a Bluefly-produced API's contract? Go to api-schema-registry — openapi/openapi.yaml (aggregated corpus), openapi/service-catalog.json, openapi/endpoints-index.json, or its published dist/serve.js HTTP surface (/openapi.yaml, /service-catalog.json, /endpoints-index.json, /control-plane.json, /health). This catalog only points at it.

How does api-schema-registry fit?

api-schema-registry is the platform's contract registry: it stores, validates, aggregates, and publishes Bluefly's own OpenAPI corpus, and it is where every Bluefly service's canonical spec lives. It is not, today, a general-purpose importer for arbitrary external vendor schemas (no URL-registration command exists in its CLI as of release/v0.1.x), and this catalog does not try to make it one. The split:

Concern Owner
Bluefly's own OpenAPI corpus: store, validate, aggregate, publish api-schema-registry
External vendor schemas: pin, provenance, hash, refresh this catalog (external/)
Pointers from Bluefly artifacts already in api-schema-registry this catalog (bluefly/)
Runtime discovery/orchestration agent-mesh, workflow-engine, compliance-engine, agent-tracer (per api-schema-registry's own README — none of that lives here either)

How do Drupal api_normalization / Tool API / MCP agents use these?

  • api_normalization (Drupal) consumes OpenAPI/schema definitions inside Drupal to normalize its own JSON:API/REST surface. It is a consumer of schemas, not a second schema catalog — it should read from api-schema-registry's published artifacts (or, for the two external vendor APIs curated here, from this catalog) rather than growing its own copies.
  • Tool API / MCP expose executable capabilities, which may be informed by a schema here but are a distinct layer (behavior, not contract storage). Neither this catalog nor api-schema-registry becomes a Drupal module or a runtime tool host.

Known gaps (recorded, not fabricated)

  • Acquia Cloud Platform API (the tenant-agnostic infrastructure API at cloud.acquia.com, distinct from Source/Drupal JSON:API): no public machine-readable OpenAPI/Swagger document could be located at https://cloudapi-docs.acquia.com/ in this session (rendered docs page only, no discoverable spec link). SCHEMA_AVAILABLE: NO — needs a developer-portal export, not a fabricated file.
  • Acquia Source JSON:API duplicate inside api-schema-registry (openapi/acquia-cms/ vs openapi/acquia-source/, byte-identical raw source, two independently-bundled OpenAPI derivatives) — classified in bluefly/acquia-source-instance/metadata.yaml, dedup tracked as a follow-up in that repo: bead bc-kac.