Aglet

Triage API version drift before upgrading a client

Version drift may come from a changed default, a dependency upgrade, or a remote deprecation boundary. Start with one operation that changed behavior. Record the version sent, client revision, response difference, and environment, then separate a contract change from a local parser or configuration mistake.

Establish what is happening

  1. Capture the selected version

    Record the endpoint, explicit version or default, client revision, environment, and request time for one changed operation. Save a redacted response shape and warning or status. Do not rely on package names alone; the wire version and server response define the observed boundary.

  2. Compare versioned responses

    Run the same synthetic request against the last known working version and the current selection when both are available. Compare fields, errors, ordering, and warnings. Note whether the change affects request acceptance, response interpretation, or only documentation and metadata.

  3. Bound the migration

    Count affected operations by version, client, environment, and outcome. List consumers that depend on the changed field or error. Keep deprecation notice, default selection, breaking response, and local adapter regression as separate possibilities until evidence narrows them.

What to carry forward

Triage ends with an explicit version, a paired behavior difference, an affected consumer set, and an evidence gap list. Stop before changing every client. Route one migration or compatibility decision to the owner with a dated review point.

Technical background: Project documentation on GitHub.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow