Skip to main content

Communicate API Changes

Context​

Microservices are being adopted. There are multiple teams, each responsible for their certain microservice(s). The teams evolve their APIs autonomously by API versioning.

Problem​

  • Consumers don't migrate to new versions.
    • Extra effort and complexity on the API provider side for supporting older API versions
    • Breaking consumers if there is a hard version change

Solution​

Establish a mechanism to convey API changes and incentivize the migration of other teams.

Regular cross-team discussions can be used to present new API versions and announce expiring APIs.

Another way is to have an integrated toolchain in place that notifies service consumers of changes. E.g., there are integrations of version control systems (e.g. GitHub) with messaging services (e.g. Slack) that can automatically notify everyone who subscribed to it that a new commit was pushed or a release was published. This mechanism can be used to announce API changes.

For expiring API versions there should be a grace period. This grace period can be used to notify consumers of the upcoming expiration. Establish logging or monitoring mechanisms to bring the use of a deprecated API on the screen of the service consumers. On an extreme level, you can even disable the expiring API for a short period to produce a brief spike of errors in the logs of the consumers.

Maturity​

More data required (only 3 sources).

Sources of Evidence​

L19:

  • Automate notifications on commits to stakeholders by toolchain integration (GitHub, Slack,...) => information flow

L32:

  • Use alerting to show others are using deprecated API versions
  • How to ensure consumer migrate
    • Grace period
      • mark as deprecated
      • turn off after grace monitoring => consequences in responsibility of consuming team
    • Interface usage monitoring
      • to evaluate if old version still receiving traffic
      • safe migration if no traffic
    • Incentivize migration
      • after grace period runs out, apply tactic
      • show alerts on usage
      • temprarily disable interface => consumers will ask what happened => give another time limit to migrate

Interview D:

  • Discoverability of APIs required
  • Introduce lunchtalk, dev-friday, etc. for presenting new APIs