liveBook · Manning

Preview state

As explained in API Design Patterns

Preview is an API version lifecycle state in which functionality may change freely and stability is not guaranteed.

Preview is an API lifecycle state for functionality still in progress. It preserves freedom to change the API, but provides no stability guarantee: client code written today may break tomorrow. section 24.3.2

Use preview deliberately:

  • Label immature functionality as Preview rather than presenting it as ready for real users. section 24.3.2
  • Expect all changes while the API is preview; users should accept the risk of frequent breakage. section 24.3.2
  • Promote a mature preview to Current when client compatibility must be protected, and put new features into the next version. section 24.3.2

A sliding version sequence

An API can label version 1 Preview in January, promote it to Current in February, and start version 2 as Preview. In later months, version 1 becomes Deprecated and eventually Deleted while newer previews advance. 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

Compare Preview with Current, Deprecated, and Deleted states, including each state's permitted change policy. section 24.3.2

How API Design Patterns covers it

How deep it goes
Explains unrestricted changes, user risk, promotion to Current, and progression through later lifecycle states.
Examples
Uses version 1 and version 2 in a monthly timeline from Preview through Current, Deprecated, and Deleted.
What it assumes
Assumes familiarity with API versions and client code while establishing lifecycle states from their practical consequences.
What you can do after
Evaluate whether API consumers can accept instability before adopting preview functionality.
How it connects
Connects API versioning with compatibility, deprecation, current versions, and deleted versions.
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.