liveBook · Manning

Stability guarantee

As explained in API Design Patterns

Stability is the property of an API remaining unchanged over time, including in ways affected by its underlying software and infrastructure.

A stability guarantee defines how much an API may change while existing users continue relying on it. Stability includes visible behavior affected by security patches, operating-system upgrades, libraries, suppliers, and other infrastructure—not only deliberate API edits. section 24.4.2

Choose the guarantee deliberately rather than inventing compatibility decisions as changes arrive:

  • Favor stability when users have limited appetite for change, such as large government organizations. section 24.4.2
  • Favor rapid functionality, bug fixes, and infrastructure updates when users prioritize new capabilities, such as startups. section 24.4.2
  • Balance simplicity against choice: one forever-version is easy to understand, while many versions increase management cost. section 24.4.1

Preview to current

Keep version 1 in Preview while developers may change it freely and users accept that today’s code may break tomorrow. Promote it to Current when mature, then permit only mandatory changes and critical fixes. Put new features into version 2 as the next Preview. Later, move version 1 through Deprecated to Deleted under a defined removal policy. section 24.3.2

Table 24.1 Overview of different version states (view table figure)

State

Description

Change policy

Preview

An unstable and still-in-progress preview of functionality users should expect to exist in the next current version

All changes permitted

Current

A very stable set of functionality that should not change and can be expected to continue running for some pre-decided amount of time

Only mandatory changes

Deprecated

A prior current version that is scheduled for impending removal according to the deprecation policy

Only mandatory changes

Deleted

A prior deprecated version that has been removed or otherwise made inaccessible to users

N/A

Use the version-state table to compare Preview, Current, Deprecated, and Deleted states with their permitted change policies. section 24.3.2

How API Design Patterns covers it

How deep it goes
Descends from trade-offs to a Preview–Current–Deprecated–Deleted lifecycle, but defers implementation details.
Examples
Uses version lifecycles, user profiles, infrastructure changes, and a timeline of successive Preview, Current, Deprecated, and Deleted versions.
What it assumes
Assumes familiarity with APIs and users, while defining stability trade-offs and version-state policies directly.
What you can do after
Operate/configure an API lifecycle with explicit stability states, compatibility rules, and deprecation decisions.
How it connects
Connects API versioning with backward compatibility, deprecation policy, security patches, and infrastructure upgrades.
Cover of API Design Patterns
liveBookmanning.com
Read API Design Patterns on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.