Explicit revision

As explained in API Design Patterns

An explicit revision is a resource revision created only when a user specifically requests its creation.

An explicit revision is created only when a user requests it. A custom method takes a snapshot of the resource at that moment, rather than creating revisions automatically whenever the resource changes. section 28.3.2

Use explicit revisions when automatic creation would be unnecessary or wasteful:

• Give the user responsibility for deciding when a revision is worth preserving. section 28.3.2
• Expose a custom create-revision method with one responsibility: snapshot the current resource. section 28.3.2
• Assign a randomly generated revision identifier and persist the creation timestamp when the revision is stored. section 28.3.2

Message revision endpoint

A chat-room API can expose POST /{id=chatRooms/*/messages/*}:createRevision. The request supplies the message ID; the response is a message carrying revisionId and revisionCreateTime. section 28.3.2

Figure 28.2 Flow diagram of explicitly creating resource revisions

Use the flow diagram to trace how an explicit request produces a resource revision. section 28.3.2

How API Design Patterns covers it

How deep it goes

Defines the custom-method workflow and metadata requirements, but stops short of implementation storage details.

Examples

Uses a chat message createRevision endpoint returning revisionId and revisionCreateTime.

What it assumes

Assumes familiarity with resource modification and revisions while defining explicit creation from the snapshot operation onward.

What you can do after

Operate revision creation by requesting snapshots through a dedicated custom method.

How it connects

Connects resource revisions with custom methods, snapshots, randomly generated identifiers, and creation timestamps.

liveBookmanning.com

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

Related concepts

• implicit revisionalternative to · An implicit revision is a resource revision that an API creates automatically according to changes, schedules, or other system-defined conditions.
• custom create revision methoduses · A custom create revision method is an API operation that captures the current state of a resource as a new revision.
• 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.