Skip to content
Componecat Docs

Interfaces

An interface is a named, typed connection point an entity exposes — an API a service serves, a package a library publishes, a CLI it ships. Modeling interfaces explicitly makes an entity discoverable: consumers know how to reach it, dependency maps can be drawn, and AI agents can retrieve the exact connectivity details they need to generate a client or an integration.

Interface kinds

Section titled “Interface kinds”
Kind Covers
API HTTP, gRPC, GraphQL, and WebSocket APIs.
CLI Command-line interfaces.
UI Web and native user interfaces.
MCP Model Context Protocol endpoints.
Data share Data feeds, queues, topics, and exported tables.
Package Published library packages (npm, NuGet, Maven, PyPI).

Each kind has its own set of fields describing how to connect — protocol, URL, and auth for an API; registry and coordinates for a package.

Interfaces describe connectivity, not implementation

Section titled “Interfaces describe connectivity, not implementation”

An interface answers “how does a consumer reach this?” — not “how is it built?”. Keep interface fields focused on the connection: endpoints, protocols, package coordinates, authentication. Implementation detail belongs in the entity’s documentation, not on its interfaces.

Visibility

Section titled “Visibility”

Every interface has a visibility — Private, Internal, Partner, or Public — recording who it is meant for. Visibility is descriptive by default. An organization can make Private binding, so that private interfaces are shown only to the owning team’s members and organization admins; see Team access control.

Importing specs

Section titled “Importing specs”

For API interfaces, Componecat can import a specification instead of you typing the shape by hand. It supports OpenAPI, gRPC reflection, and GraphQL introspection. Imported specs are stored on the interface and rendered inline in the catalog, so anyone (or any agent) browsing the entity sees the live contract.

Checking that APIs are used and documented

Section titled “Checking that APIs are used and documented”

Interfaces and API-provider relationships describe the same contract from two sides: the interface says what an entity exposes, and the relationship says who consumes it. Scorecard graph rules can check that the two agree — Has consumer flags an entity whose interfaces no one consumes (a dead endpoint), and Provider exposes interface flags an entity that consumes from a provider declaring no interface (an undocumented contract). Both can be limited to particular interface kinds, such as API only.

Declaring interfaces

Section titled “Declaring interfaces”

Add interfaces from an entity’s page, in a componecat.yaml descriptor, or through the APIs:

interfaces:
  - kind: api
    name: Payment API
    protocol: grpc
    url: grpc://payments.internal:443
Section titled “Related”