Design items

A design item describes how one feature of APIHUB behaves: its purpose, the actors, the flow, the rules, and the API it uses. Design items are the specification that the Portal, the backend, and the agent implement and that tests check. Each item is one Markdown file in the folder of its area. Files change together with the behavior they describe.

Areas

Each area has a folder. On the docs site the links below open the first item of each area; the lists after the ID scheme name every item.

General features: Navigation, workspaces, groups, packages, favorites, shared packages, activity history, search.
Package version: What a user sees and does in a published package version: operations, documents, exports, history, quality.
Package settings: Settings of a package: general, versions list, access tokens, release version rules, preserved OAS extensions.
Global settings: System-wide administration: roles, system tokens, business metrics, rulesets, version validation.
Operation view: Rendering and trying out a single operation: schema rendering, playground, examples panel.
Comparison: Severity of changes and the API changes view.
Dashboard version: Configuring and editing dashboard versions.
User settings: Settings of the current user, such as personal access tokens.
Custom OpenAPI extensions: APIHUB-specific OpenAPI extensions, such as x-api-audience.
VS Code extension: Publishing to the Portal from VS Code.
Agent: Behavior of the APIHUB agent: version validation and cloud services.
Contract types: Design pages for contract types, such as AsyncAPI.
AI assistant: The AI chat in the Portal: feature design, frontend contract, IDS document generation.

ID scheme

An ID has the form DI-<Product>-<AREA>-<NNN>:

<Product> is Portal or Agent.
<AREA> is the area code from the table below. Agent items have no area code: DI-Agent-<NNN>.
<NNN> is a three-digit number, counted per area, starting at 001. A number is never reused, even after the item is deleted.

The next free number is computed from every ID that appears in a title or in a body in this folder.

Area	Code	Folder	Items	Next free number
General features	GF	`general/`	12	`DI-Portal-GF-011`
Package version	PKGVER	`package-version/`	24	`DI-Portal-PKGVER-025`
Package settings	PS	`package-settings/`	7	`DI-Portal-PS-008`
Global settings	GS	`global-settings/`	7	`DI-Portal-GS-009`
Operation view	OPVIEW	`operation-view/`	3	`DI-Portal-OPVIEW-004`
Comparison	COMP	`comparison/`	3	`DI-Portal-COMP-004`
Dashboard version	DSHVER	`dashboard-version/`	2	`DI-Portal-DSHVER-003`
User settings	US	`user-settings/`	1	`DI-Portal-US-002`
Custom OpenAPI extensions	COE	`custom-openapi-extensions/`	1	`DI-Portal-COE-002`
VS Code extension	VCE	`vscode-extension/`	1	`DI-Portal-VCE-002`
Agent	-	`agent/`	2	`DI-Agent-003`
Contract types	-	`contract-types/`	3	no IDs
AI assistant	-	`ai-assistant/`	3	no IDs

PKGVER-021 is reserved: the “AI Recommendations Tab” item has an ID but its page is not in the repository yet. GS-008 is reserved for the planned “Search Scope for GraphQL Operations” item, which has no page yet. Items can be referenced by ID before their page exists; the numbers still count as used.

File naming

Name a file <id>-<slug>.md, in lowercase ASCII with hyphens, for example package-version/di-portal-pkgver-011-list-of-operations.md. The slug is the item name. A page that is not a numbered design item keeps a plain slug, such as global-settings/ruleset-severity-downgrade.md.

Template for a new design item

Copy this header block and fill it in. The file starts with one H1 that repeats the ID and the name. Put the sections below the block at the second level (##).

# DI-Portal-<AREA>-<NNN> <Item name>

**Design Item ID**: DI-Portal-<AREA>-<NNN>
**Design Item Name**: <Item name>
**Related Design Items**:
  - [DI-Portal-<AREA>-<NNN>: <Name>](<file name>.md)

**Related API**:
  - <What the call does> (<METHOD> /api/v<N>/<path>)

**Revision History:**

| Date | Description |
| ---- | ----------- |
| <YYYY-MM-DD> | <What changed> |

***

## Description

<What the feature does and for whom.>

## Start point

<How the user reaches the feature.>

## Flow

<Steps, rules, and error cases.>

Use - after Related Design Items: and Related API: when there is nothing to list.

Items by area

General features

Navigation to APIHUB (log in - log out) (GF-001)
Create Workspace (GF-002)
Create Group (GF-003)
Create Package (GF-004)
Favorite packages, dashboards, groups, workspaces (GF-005)
Shared Packages (GF-006)
Activity History in Main Page (GF-007)
Personal Private Workspace (GF-008)
Relevance of API-Processor Versions (GF-009)
Global Search v4 (newer revision of GF-010) (GF-010)
Global Search (GF-010)
Search Scope for REST API (GS-007)

Package version

Version Summary (PKGVER-001)
Revision History (PKGVER-002)
Package Activity History (PKGVER-003)
Manage Manual Operations Group (PKGVER-004)
Export Operations Group (reduced source specifications) (PKGVER-005)
Export Operations Group (combined specification) (PKGVER-006)
Search and Filter Operations (PKGVER-007)
Export List of Operations in Excel (PKGVER-008)
List of Operations Groups (PKGVER-009)
Manage REST Path Prefix Group (PKGVER-010)
List of Operations (PKGVER-011)
Activity History (PKGVER-012)
Export List of Changes in Excel (PKGVER-013)
List of Deprecated Operations (PKGVER-014)
Human-readable description for deprecated items for OpenAPI 3.0 (PKGVER-015)
List of Documents (PKGVER-016)
Copy Package Version (PKGVER-017)
Export Package Version (PKGVER-018)
API Quality Validation Result (PKGVER-019)
Export of discrepancy analysis results for arbitrary package versions in Excel (PKGVER-020)
OpenAPI Document Overview (PKGVER-022)
Export Document from Package Version (PKGVER-023)
Export List of Deprecated Operations in Excel (PKGVER-024)
Document Shareability

Package settings

General Settings (PS-001)
Package versions list (PS-002)
Access Tokens Management (PS-003)
Delete Package (PS-004)
Default Release Version (PS-005)
Define Release Version Pattern (PS-006)
Configure List of OAS Extensions Preserved on Export (PS-007)

Global settings

Manage Roles (GS-001)
Manage System Tokens (GS-002)
Roles Hierarchy (GS-003)
Business Metrics (GS-004)
Ruleset Management for API Quality Check (GS-005)
Version Validation (GS-006)
Ruleset Severity Downgrade

Operation view

REST Operation Schema Rendering in Doc View (OPVIEW-001)
Playground (OPVIEW-002)
Examples panel (OPVIEW-003)

Comparison

Semi-breaking severity of changes (COMP-001)
Severity of Changes (COMP-002)
API Changes (COMP-003)
Semi-breaking reclassification: sequence diagram (source)

Dashboard version

Configure dashboard version from scratch (DSHVER-001)
Edit dashboard version (DSHVER-002)

User settings

Manage Personal Access Tokens (US-001)

Custom OpenAPI extensions

API Audience (x-api-audience) (COE-001)

VS Code extension

Publish to Portal from VS Code (VCE-001)

Agent

Version Validation (Agent-001)
Cloud Services (Agent-002)