Skip to content

How API Collection Changes Affect Client Types

URI parameters, query parameters and payload fields are references to an operation of an API collection. When that collection changes, BizMetry updates the client types automatically and immediately, so they never point to something that no longer exists.

The Events

Event Effect on the client types
An API collection is removed from the template All the references to that collection are dropped.
An operation is removed from a referenced Swagger All the references to that operation are dropped.
A field or parameter is removed from a referenced Swagger The references to it are dropped.
A collection is replaced by another of its versions in the template References move to the same field of the new version. Those whose field no longer exists are dropped.

An API collection used by a template can't be deleted: it has to be removed from the template first.

Only unpublished collections can change their Swagger

Editing a PUBLISHED collection creates a new DRAFT version, and templates keep using the published one. Client types are affected only when a template is switched to the new version.

What Gets Removed

The change is applied per reference:

  1. The reference to the affected operation is dropped.
  2. A field or parameter that another operation still references stays.
  3. A field or parameter with no references left is removed from its criterion. The criterion's other entries remain.
  4. A criterion with no references left is removed. The client type's other criteria remain.

Example. A type has a Request Payload Fields criterion with agent_id from createAgent and updateAgent, and tenant from listAgents:

Change Result
createAgent is removed from the Swagger agent_id stays, referenced by updateAgent
updateAgent is removed too agent_id goes; the criterion stays with tenant
listAgents is removed too The criterion is removed

Which Template Versions Change

Template version status Effect
DRAFT Its client types are updated.
PENDING REVIEW, REVIEWED or REJECTED Its client types are updated when the content changes, and it returns to DRAFT.
PUBLISHED or RETIRED Not modified. It keeps its criteria.

Lifecycle of a Change

%%{init: {"themeVariables": {"fontSize": "16px"}}}%%
flowchart TB
    A["API collection changes or leaves the template"] --> B["Unpublished template versions lose the affected references"]
    B --> C["Reviewed versions return to DRAFT"]
    C --> D["Template version is reviewed and PUBLISHED"]
    D --> E["Version is assigned to an environment in the Release Pipeline"]
    E --> F["Clients of that environment are reconciled"]
  1. The change happens. The references are updated when the collection or the template is saved. Clients are not touched yet.
  2. Review. Check the client types of the version in the template editor or in the Template Explorer.
  3. Publishing. A version can't be published while a URI parameter, query parameter or payload field has no API collection reference. Such an entry appears struck through in the client type dialog: remove it or pick it again.
  4. Assignment. Only when the version is assigned to an environment do its clients follow it: see How Clients Are Reconciled.