API Catalog

The API Catalog is the inventory of every API your account knows about. Each entry is synced from a connected gateway or added by hand. You open it under Catalog, then API Catalog. Catalog-bound plans draw their APIs from it, and once you switch to catalog-led documentation, it also owns the specifications your plans serve.

What is the API Catalog?

It is the list of every API Apiable knows about for your account. Entries come from connected gateways or are added by hand as custom APIs. Catalog-bound plans select their APIs from it.

Each entry carries the API's name, URL, description, tags, owning team and specification. The same entry is where you write per-operation documentation and generate SDKs, whether or not your portal is catalog-led.

How do APIs get into the catalog?

Three ways. Connecting a gateway adds its APIs automatically. Synchronize refreshes every connected gateway. + Custom API adds an API that is not on a connected gateway.

The automatic sync on connect is best effort. If it fails, the gateway stays connected and Synchronize fills the catalog later.

On a custom entry you can edit the name and URL. On a synced entry the gateway supplies them, so you edit the description, tags, owner, specification and operation documentation.

Refresh the catalog from your gateways

1. Open Catalog, then API Catalog.
2. Choose Synchronize.
3. Wait for the API catalog synchronized message. The list refreshes with each gateway's current APIs.

A sync also removes entries whose gateway you have deleted. Custom entries are never removed or changed by a sync.

Add a custom API

1. In the API Catalog, choose + Custom API. The Add custom API item dialog opens.
2. Optionally pick a team under Claim this API for your team:.
3. Enter a Name and a URL.
4. Add a Description and any Tags.
5. Optionally, under Documentation, upload the API's OpenAPI specification. You can also add it later on the API's Specification tab.
6. Choose Save Changes.

The new entry appears in the list marked Custom.

What does the catalog list show?

One row per API. A column selector next to Synchronize chooses which columns show. Clicking a row opens the API's view.

The row menu offers Edit and Delete. Delete removes the entry straight away, with no confirmation step, so check which plans use the API first. A deleted gateway API is added again, as a new entry, at the next sync. A deleted custom API is gone.

A scope count appears once scopes in a Resource Group reference the API. See Resource groups and scopes.

What do Available and Unavailable mean?

Available means the last sync found the API on its gateway. Unavailable means it could not, usually because the API was removed or renamed on the gateway.

Run Synchronize to refresh the status. If a sync cannot reach a gateway at all, Apiable leaves that gateway's entries as they were rather than marking them all Unavailable.

What can I change on a catalog API?

Open an API to see its view. Its tabs split the entry into what the API is, its specification, its operations, its SDKs and its scopes. The view is read-only unless you belong to the API's owning team or the API is unclaimed.

Choose Save Changes to keep your edits, or Cancel to drop them. Saving a new specification is what can create a new version on a catalog-led portal. Editing a description, a tag or an override never does.

How do operation overrides work?

An override replaces how one operation reads in your documentation without touching the specification. Apiable stores it on the catalog API and applies it when it serves the documentation, so it survives a gateway re-sync or a new CI/CD upload.

1. Open the API and select the Operations tab.
2. Find the operation. Search by path, operation ID or summary, or tick Only incomplete to list operations with empty fields.
3. Select the operation and fill in what you want to change: Summary, Description, Tags, Deprecated, Hide from documentation, parameter descriptions and examples, or response descriptions.
4. Choose Save Changes.

An overridden operation shows Overridden. If the specification changes under an override, the operation shows Spec changed and your text keeps being served until you review it and save again. Reset to specification removes the override. Overrides whose operation has disappeared from the specification are listed under Overrides with no matching operation, with Remove.

Overrides apply wherever Apiable serves the API's specification from the catalog: in combined plan documentation, in the Full API Reference of a catalog-led portal, and in the per-API plan documentation that signed-in developers read. Download documentation on the Specification tab includes them.

How do I generate SDKs for a catalog API?

On the API's SDKs tab. SDKs belong to one version of the specification, so each version has its own. On a catalog-led portal, every plan that serves that version offers them.

1. Open the API and select the SDKs tab.
2. Under Generate SDKs, pick one or more Languages.
3. Choose a Visibility: Public, Private or Subscribers only. The default is Private.
4. Choose Generate. Generation can take a while.

The API needs a specification first. When a new version is captured, it keeps the same languages and rebuilds them against the new specification. Until a rebuild finishes, that SDK shows Building… and plans do not offer it.

What does catalog-led documentation change?

It moves the specification, its versions and its Deprecated and Beta markers from each plan to the catalog API. Plans then reference the API and either follow its latest version or pin one. The switch is one-way.

Before the switch, each plan carries its own copy of a specification, its own version list and its own markers. After it:

• The catalog owns specification versions. Each API keeps a Specification history. Apiable records a new version when the specification's content changes, from Synchronize, an upload or a CI/CD publish. Once an API has more than one version, the list shows how many.
• The catalog owns the markers. The Status card on the API's Overview tab sets Visible, Deprecated and Beta for the version you are viewing. A newly captured version starts unmarked and visible.
• Plans follow or pin a version. On a plan's Documentation tab, each API follows the catalog or serves a manual upload. A following API serves the latest version, or a version you pin. See Attach documentation to a plan.
• CI/CD publishes to the catalog. Pipelines publish specifications to the catalog API instead of to plan documentation.
• The Full API Reference is composed from the catalog. See Portal API reference.

How do I switch to catalog-led?

Use the banner at the top of the API Catalog. It is titled Let the API Catalog master documentation and shows only until your portal has switched.

1. Open Catalog, then API Catalog.
2. In the banner, choose Switch to catalog-led. The button needs a role that manages the catalog.
3. Read the Switch to catalog-led documentation? confirmation, then choose Switch to catalog-led.

Apiable copies the Deprecated and Beta markers from plan documentation that is linked to a catalog API onto that API's latest version. If any plan marked an API deprecated or beta, the API is marked. The switch itself does not modify or delete plan documentation. Apiable then synchronizes the catalog from your gateways in the background, and the version history and Status card appear.

From then on, an API that a plan takes from the API Catalog serves the catalog's specification. If a plan held its own uploaded documentation for such an API, that file stops being served, and Apiable drops it the next time you save the plan. Keep a copy of those files before you switch. To serve one again, set that API to Manual upload on the plan's Documentation tab, save, then upload the file and save again.

How do I work with versions after the switch?

Open an API and use the version chip next to its name. It opens the Specification history, newest capture first, with Current on the latest version and Viewing on the one you have open.

• Select an older version to open it. Its specification is a read-only record of what was served, but you can still mark it Deprecated, Beta or not Visible on its Status card.
• A version you hide stops appearing in the version lists of plans that follow the API.
• Two captures can carry the same version string, so each row also shows when it was captured.

How does CI/CD publish after the switch?

A pipeline publishes the new specification to the catalog API through the Platform API, using the API's stack address, which stays the same across versions. Apiable re-reads the specification and records a new version only when the content changed, so publishing on every build does not fill the history with duplicates.

Operation overrides carry forward onto the new version. A pipeline that still writes to a catalog API's plan documentation is refused, with a message that names the catalog endpoint to use. See CI/CD documentation sync and the Platform API.

How does the catalog feed plans?

A Catalog-bound plan draws its APIs from the API Catalog, so it can package APIs from more than one gateway. A Gateway-bound plan takes its APIs straight from one gateway.

An API has to be in the catalog before a Catalog-bound plan can include it. See Add APIs and choose coupling.

Troubleshooting

Where to next