Last updated 1 year ago

API registry orientation

The API registry serves as a single-source of truth for API definitions.

APIVersionsBranchesDefault-branchSnapshotshashascontainshas

API

Add an API. An API is represented by a "name" and is a concept that represents the set of use cases the underlying API will offer. An API will have one or more versions.

Versions

Then, add at least one version. A version maps to a specific OpenAPI definition. A version may have more than one branch. A branch loosely mimics a branch in git, where you may prepare a change.

A version will be connected to a source (such as GitHub).

A version has history. The version history logs and bundled versions are available.

Default branch

Each version must specify a default branch. The default branch maps to the production build. The other branches maps to preview builds.

When a change occurs in the default branch, it will trigger the validation, bundling, and then subsequent building of any connected OpenAPI definitions, reference docs, and developer portal projects to production.

When a change occurs in another active branch, it will trigger the validation, bundling, and then subsequent building of any connected OpenAPI definitions, reference docs, and developer portal projects to a preview location.

When an active branch is deleted from the connected source, it will be removed from the active branches list.

Change default branch

You may change the default branch at any time from the version settings page.

Snapshots

A snapshot refers to a bundled OpenAPI definition. There may be many snapshots for any given branch.

Link to your bundled API definition (snapshot) from the registry in other API definitions or in reference docs and developer portals. This helps to use your API definitions as a single-source-of-truth.

You may link to a branch's latest snapshot, or a specific point-in-time snapshot. Doing this will register the usage and dependency linkage. That will automate previews and deployments upon changes to the dependency. A specific "point-in-time" snapshot will not change, and therefore will not trigger further updates as a dependency. A "latest" branch snapshot may change, and will trigger updates as a dependency.

Access controls

API registry links to snapshots may be protected by access controls or available to the public. Control access to your API registry links for each specific version from the settings.