Software ArchitectureAtlas

Software Architecture Atlas

Gain an overview. Understand the connections.

MechanismChapter II · Communication · Building block 9 of 9

API versioning

API versioning makes changes plannable for existing users. Compatible extension, parallel operation and replacement each need clear rules.

By Michael Meierhoff · Meierhoff Systems

  1. Compatible changeOld users work unchanged.
  2. Breaking changeBreaking existing users.
  3. Tolerant ReaderUsers ignore unknowns.

Context

Why this is important

If an interface changes its meaning unannounced, existing users break. Compatible extensions and planned transitions keep changes manageable. The current content is the subject of API contracts.

This building block explains the development of existing interfaces. For their current content, see API Contracts.

At a glance · Two versions side by side

Old and new clients call separate versions v1 and v2; both end up in the same service.
Shop example · Breakage test

Does this change break users?

The warehouse module extends the reservation response with expiresAt. Later, the existing field available should change from a number to a business availability level.

This is how you read the picture

  1. Compatible change The judgment is compatible, for example with optional expiresAt.
  2. Breaking change The judgment breaks users, for example, when removing available.
  3. Tolerant Reader The judgment only with Tolerant Reader for a new status value or error code.

Reservation response of the camp

CompatibilityOptional field extendsAt

Old users ignore the unknown field and continue reading as before.

→ Publish as a secondary version

Choose a change; the image shows whether existing users are breaking and what to do.

Further develop the reservation agreement

  1. v1

    Existing contract

    reservationId and available as a number

  2. v1.1

    Compatible complement

    optional expiresAt; old users read on

  3. Transition

    Observing usage

    Order takes over expiresAt

  4. v2

    Changes in meaning

    AvailabilityLevel replaces Available

  5. Replacement

    v1 consumer ended

    Remove old variant after proof

The timeline separates the compatible addition from the later breaking transition and detachment.

Benefits & limitations

Helps if:

  • Incompatible contract changes can be migrated controllably with versioning and parallel operation.
  • Usage measurement shows which older consumers are still active and when a replacement becomes viable.
  • An explicit new contract version keeps changes in meaning separate from existing assumptions.

Boundaries

  • Parallel versions increase maintenance and security work; measure usage and schedule retirement.
  • Additive changes can change meaning; check real user assumptions instead of just schema compatibility.
  • Retirement needs fallback and migration plans. Data Migration covers stored data; API Contracts protects behavioural guarantees.

In practice

  1. Assess schema and semantic changes and classify their compatibility. Additive structural changes and changes in meaning need different migration paths.
  2. Introduce new contract versions alongside existing ones and measure consumer usage. Define owners, a schedule and a fallback option for retirement.
  3. Remove old versions only after verifying migration. API Contracts defines observable behaviour; Data Migration covers stored data.
Read the detailed explanation

Versioning makes incompatible contract changes explicit and gives providers and consumers a migration path. Compatibility includes data structure and business meaning; an unchanged type does not guarantee unchanged semantics.

Additive extensions often support parallel operation, while removing or reinterpreting fields may break existing consumers. Usage measurements show when an older contract version can be retired.

API Contracts defines the observable behaviour that should remain stable; Data Migration addresses the separate evolution of stored structures.

Semantic Versioning expresses compatibility through version numbers. A Tolerant Reader ignores unknown fields, making additive extensions easier to accommodate.

Check your understanding

Test yourself in three stages

  1. ReadingCheck in the picture

    What judgment does the optional field diesAt carry, and what action follows?

    View the solution with justification

    Compatible. Old users continue to read; the change appears as a secondary version.

  2. ApplyingTransferred to a new situation

    The camp changes the meaning of available, the field remains the same. Are users breaking?

    View the solution with justification

    Yes, as a silent break: data type and name remain, but users misinterpret the value. Introducing a new field instead of re-interpreting the old one.

  3. EvaluateWeighing an alternative

    A new status value is to be added. What are you doing?

    View the solution with justification

    Advantage: small, additive change. Risk: Users without Tolerant Reader break into unknown values. Recommendation: Check users in advance and record the tolerance in the contract.

Explore further

These building blocks continue the thoughts of this page.

CommunicationAPI contractsAPI contracts define data, meaning and observable interface behavior as binding rules.Opening RequirementsModifiabilityHere you assess the effort and risk of a specific business or technical change.Opening EvolutionData migrationData migration coordinates changes to data models with software versions running in parallel.Opening

References

Continue on the learning path

With that, you have Communication & APIs run through. It continues with Distributed systems.

9 Building blocks

Next areaDistributed systems