API Design

Components

Components are reusable building blocks defined once per specification and referenced from many endpoints. Instead of repeating the same NotFound response, CreateUser request body, or PageSize parameter on every operation, you define it as a component, reference it everywhere, and update it in one place. Components map directly to OpenAPI's components section, so they import and export cleanly.

The Components section

The Components section at the bottom of the designer sidebar groups all reusable definitions of the selected version:

Subsection What it holds
Shared Components linked from the cross-project shared library.
Schemas Reusable data structures — see Schemas.
Responses Complete reusable responses: content type, body, headers, example.
Parameters Reusable parameter definitions.
Headers Reusable response-header definitions.
Header Policies Rules that inject headers across endpoints — see Header policies.
Request Bodies Reusable request body definitions.
Security Security schemes applied to endpoints.

Each subsection has a + button to create a component, shows a usage-count badge per item, and lists validation issues as a colored status line. Component names use PascalCase (e.g. NotFound, CreateUser, BearerAuth); the create dialogs enforce this.

The Components section in the sidebar with responses and request bodies

Response components

A response component packages everything a response needs — description, content type, body (inline properties or a linked schema), headers, and example — under a name like NotFound or ValidationError.

  • Create one from the Responses subsection, or extract one from an existing endpoint response with Extract to Component — the endpoint is re-linked to the new component automatically.
  • Use it by dragging the component from the sidebar onto an endpoint's responses area: dropping adds a response backed by the component (or replaces the one you drop it on). The response card then shows the component's badge — click it to jump to the component editor.
  • Update the component and every endpoint that references it reflects the change.

Request body components

A request body component defines a Content Type (application/json, application/xml, form, text, or binary types), a Required flag, a description, and the body structure — inline properties or a linked schema.

  • Create one from the Request Bodies subsection, or extract from an endpoint with Extract to Component on the request body editor.
  • Use it by dragging it onto an endpoint's request body area — the drop zone shows "Drop component here to link" (or "Drop to replace with component" if a body already exists). The linked component appears as a badge on the endpoint.

Parameter components

A parameter component captures a parameter definition — Location (Query, Path, Header, or Cookie), Schema Type, Format, Example Value, Default Value, Required, and Deprecated — so recurring parameters like pagination or tenant headers have one source of truth. Create them from the Parameters subsection; specs imported from OpenAPI keep their $ref parameters as parameter components, and each component's Used by section lists the endpoints that reference it.

Header components

Header components are reusable response-header definitions (name such as X-Rate-Limit, schema type, required flag, description). Link them from a response's headers table, or let header policies inject them across endpoints. Headers defined at the organization or project level in Settings appear here as inherited, read-only entries alongside your spec-level headers.

Security schemes

Security scheme components describe how your API authenticates callers. Four types are supported: HTTP, API Key, OAuth2, and OpenID Connect. Create a scheme (e.g. BearerAuth) from the Security subsection, then attach it to endpoints with the Add button next to the security badges in the endpoint editor header — each endpoint lists its assigned schemes as removable badges.

Assigning a scheme to many endpoints

Attaching BearerAuth to sixty endpoints one badge at a time is the kind of task people skip, and an endpoint nobody got around to securing looks exactly like one that is deliberately public. Assign {scheme} to endpoints does it in one step, with four ways to choose the targets:

Scope Targets
All endpoints Everything in the specification.
Folder One folder — pick it from the list.
Tag Everything carrying one tag.
Manual Search and tick individual endpoints.

Endpoints that already carry the scheme are marked Already assigned rather than silently skipped, and a preview shows what the assignment will touch before you confirm.

Usage tracking and validation

Every component editor has a Used by section listing the endpoints that reference it — click an entry to jump to that endpoint. In the sidebar, a link badge shows each component's reference count, and a colored status line surfaces validation errors and warnings. Components save automatically, just like endpoints.

Deleting a component

Deleting a component is confirmed with a warning that endpoints referencing it will need to be updated — the deletion is not blocked, so check the Used by list first. Deleting cannot be undone.

Seeing the whole project at once

Components live inside one specification, but the duplication you want to find usually happens between specifications — the same Address schema written three times because three teams needed it. The project components view answers that: it lists endpoints and schemas across every specification in the project, each row badged with the spec it belongs to.

Two tabs, each with its own filters:

Tab Filters
Schemas All, Duplicates, Unreferenced
Endpoints All, Duplicates, Deprecated

Duplicates is the interesting one, and neither tab detects them by name:

  • Schemas are grouped by their structure. Address, PostalAddress and CustomerAddress land in one group when their fields match — the case you would never find by searching. Each group can be promoted to the shared library in one step, turning three copies into one definition the specs reference.
  • Endpoints are grouped by method and normalized path: parameter names are ignored, duplicate and trailing slashes collapsed. So GET /items/{id} and GET /items/{itemId} are the same endpoint, because they are — the placeholder name is yours, the route is what callers see. Case is deliberately not normalized: /Users and /users are different resources, so calling them duplicates would be wrong.

Unreferenced lists schemas nothing points at any more — the residue of refactorings, and the safest deletions you will ever make. It needs the usage counts to be loaded, so it stays disabled for a moment after opening the tab.

Filter by name, description, path or summary, and narrow to a single specification when a project has grown past the point where the full list is useful.

Shared library

Components that should be identical across projects — a company-wide error response or schema — live in the shared library. Use Promote to Library on a schema or response component to publish it, and the Shared subsection's + button to link library components into a spec. Linked components carry an Org or Project badge, show a pulsing indicator when a newer library version is available (accept the update with one click), and can be unlinked at any time.

Permissions

Creating and editing components requires specs:write (included in the Member role); deleting components and promoting to the library require specs:delete and specs:write respectively — the corresponding menu items are hidden without the permission. On a published, locked version all component editing is read-only.