Implicit revision

As explained in API Design Patterns

An implicit revision is a resource revision that an API creates automatically according to changes, schedules, or other system-defined conditions.

An implicit revision is created by the API when system-defined conditions occur, rather than after a user explicitly requests one. When revisions are supported, initial creation must populate revisionId. section 28.3.2

Common policies include:

• Create a revision whenever stored data changes; this preserves the most history and is generally the safest option. section 28.3.2
• Create revisions on a schedule, after a fixed number of modifications, or when defined milestones are reached. section 28.3.2
• Avoid mixing implicit and explicit strategies unless the reason and resulting interaction patterns are clearly documented. section 28.3.2

Revision history for an issue

An issue-tracking API can automatically create a new revision whenever its stored data changes, preserving the issue’s history without requiring a separate revision request. section 28.3.2

Figure 28.1 Flow diagram of implicitly creating revisions when updating.

Shows the update flow in which the API implicitly creates a revision. section 28.3.2

How API Design Patterns covers it

How deep it goes

Explains automatic, scheduled, interval-based, and milestone-based policies, but does not detail their implementation.

Examples

Uses Google Docs revision history, GitHub issue tracking, scheduled revisions, and every-third-modification policies.

What it assumes

Assumes resource revisions exist and teaches that initial resource creation must populate revisionId.

What you can do after

Build it from scratch by selecting and documenting conditions that automatically create resource revisions.

How it connects

Connects resource revisions with revision history, resource updates, and explicit revision creation.

liveBookmanning.com

Read API Design Patterns on liveBook Get the book at manning.com

Related concepts

• explicit revisionalternative to · An explicit revision is a resource revision created only when a user specifically requests its creation.
• resource revisionkind of · A resource revision is a distinct historical state of an API resource that can be retrieved or otherwise operated on separately from other states.

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.