Docs

APIs

What this screen is for

The APIs section lists the APIs registered in the catalog and shows their definitions. It answers “what can I call, and what does it expect?” without having to find the owning team first.

Before you start

To do this You need
Browse APIs catalog read access

APIs are catalog entities, registered the same way as components — see Settings › Development › Projects.

Opening it

  1. Explore › APIs in the sidebar.

Direct URL: /api-docs

The interface

📸 Screenshot Placeholder: The APIs list with one API open. Mark: (1) the API list, (2) the owner column, (3) the definition view, (4) the consumers and providers.

# Control What it does When you’d use it
1 API list Every registered API Browsing
2 Owner The team responsible Before you depend on it
3 Definition The API specification, rendered Working out how to call it
4 Consumers / providers Which components use or serve it Judging whether a change is safe

Walkthroughs

Find out how to call an API

  1. Explore › APIs, find it.
  2. Read the definition.
  3. Note the owner before you build against it — an API with no owner is one whose changes will arrive without warning.

Check who consumes an API before changing it

Open the API and read its consumers. Then confirm in Architecture, which shows the same relationships as a graph and makes transitive consumers visible.

Scenario

You are about to make a breaking change to an API you own.

  1. Explore › APIs, open your API.
  2. Read the consumers. This is the list of teams you owe a conversation.
  3. Open Architecture and search for the API, to catch consumers that reach it indirectly.
  4. Check each consumer’s owner in the Catalog. Consumers with no owner are the dangerous ones: nobody will speak up when you break them.
  5. Only registered consumers appear. Treat the list as a minimum, and announce the change more widely than it suggests.

When it doesn’t work

Symptom Cause How to check Fix
An API is not listed It is not registered as a catalog entity Projects Register it
Definition does not render The specification is missing or malformed The entity’s definition Fix the spec in the source repository
No consumers shown Relationships are not recorded in the catalog The entity’s relations Add them to the entities
Owner is blank The owning system has no group Catalog Set the owner

Next