Qubership APIHUB — user guide

Audience: API producers and consumers using the Portal: browsing specifications, comparing versions, publishing packages, dashboards, Agents discovery UI (where licensed). Administrators should follow Admin guide and Installation guide.

This page gives the vocabulary and the everyday workflows. The step-by-step guides are Portal, Agents, and making a service discoverable. Screenshots of the Portal are in the root README.

Product vocabulary

Concept	Meaning
Workspace	Top-level tenancy boundary (team/product line). Holds groups, dashboards, ACLs.
Group	Folder-like organization inside a workspace.
Package	Container for APIs belonging to one service/application; owns documents and builds.
Dashboard / virtual package	Aggregates links to packages or nested dashboards rather than owning raw specs.
Version / revision	Published evolution of a package; revision is the granular publish artifact processed by Builder. Typical statuses include release and draft.
Document	Uploaded spec or supporting file normalized by Builder (OpenAPI, AsyncAPI, GraphQL schema or introspection, Markdown, JSON Schema, etc.).
Operation	Atomic contract surfaced from specs (REST path/method, GraphQL field lineage, messaging channels… depending on API type).

Typical workflows

Find an API: search global index, filter workspace catalog, inspect package cards for backward-compatibility flags and recent releases.
Read docs: drill into Doc view for an operation — parameters, payloads, schemas, examples (format-dependent).
Compare releases: choose two semantic versions inside a package; inspect breaking vs non-breaking deltas and changelog narrative generated by Builder. The API changes reference lists the rule behind each classification.
Publish/update: upload archive or CI integration (organization-dependent); Builder resolves references, derives operations, diff against previous baseline. Large uploads constrained by businessParameters.publishArchiveSizeLimitMb / publishFileSizeLimitMb (operators tune in backend YAML / Helm env).
Export/share: offline export and shareability options where enabled by admins.
Quality scoring / lint: if API Linter is attached, inspect findings from Spectral plus optional AI commentary for eligible OpenAPI payloads.
Agents discovery (where deployed): Operators register clusters/agents separately; Analysts approve promotions from snapshots into workspaces—see Agents guide below.

Step-by-step guides

Area	Page
Workspaces, packages, versions, comparison, operations	Portal user guide
Discovering services in a cluster and promoting them	Agent user guide
Making your service discoverable by the agent	Agent discovery
How APIHUB classifies each kind of API change	API changes reference
Roles and personal access tokens	Manage Roles, Manage Personal Access Tokens

Behind the Builder (mental model)

The Builder resolves external refs (Swagger/OpenAPI/AsyncAPI chains), derives normalized operations, classifies deltas (breaking, safe, annotations), emits human-readable changelog text, persists artifacts inside the Registry. Knowing this explains why malformed references or gigantic archives fail fast—ask administrators to review limits and logs when publishes stall.

Supported input families include Swagger 2, OpenAPI 3.x, GraphQL schema & introspection, AsyncAPI (per current product matrix — see the features list).

When something breaks for you

Symptom	Likely next step
Cannot log in	Contact admins about IdP outage vs `productionMode`, expired SAML metadata, PAT revocation.
Publish stuck / failed validation	Inspect error banner; ensure archive obeys size limits and references resolve offline; escalate with build ID if surfaced.
Missing operations after upload	Possibly filtered API type/build error—attach package ID + timestamp for support.

End-user settings (language, PATs where allowed, favorites, notifications) persist per account; resetting browser storage without logout may drop unsaved drafts.