Resource revisioning retains distinct historical snapshots of an API resource as it changes. Each snapshot has the resource’s identifier, a unique revision identifier, and a creation timestamp. The ordinary resource identifier refers to the latest revision, while historical revisions preserve change history and support diagnosis or rollback. section 28.1 section 28.2
Listing 28.1 Adding support for revisions to a Message resource
interface Message {
id: string;
content: string;
// ...
revisionId: string; #1
revisionCreateTime: Date; #1
}
A Message resource gains revisionId and revisionCreateTime fields without requiring a separate resource interface. section 28.2
A complete revision API typically provides:
- Get the latest revision with the standard get method, or retrieve a specific revision by appending its identifier with an “@” separator, such as /chatRooms/1/messages/2@1234. section 28.3.3
- List revisions through a custom listRevisions method attached to the resource; retain standard listing behavior such as pagination. section 28.3.4
- Restore an earlier state through a custom restoreRevision method that creates a new latest revision rather than moving or rewriting history. section 28.3.5
- Delete individual revisions with a distinct deleteRevision method, making destructive revision deletion harder to confuse with deleting the resource itself. section 28.3.6
Message revision history
A chat message at /chatRooms/1/messages/2 represents its latest state. A request for /chatRooms/1/messages/2@abcde reads an earlier snapshot. Restoring that snapshot creates another revision at the top of the history, so users can see both the original change and the later restoration. section 28.3.3 section 28.3.5
Choose and apply revisioning deliberately:
- Create revisions implicitly when resource data changes, or explicitly when users request them; use one strategy consistently across revisable resources. section 28.3.2
- Populate revisionId when the resource is first created, regardless of the chosen creation strategy. section 28.3.2
- Use random revision identifiers rather than incrementing numbers or timestamps, and avoid revisioning child hierarchies unless business requirements justify their added complexity and storage. section 28.3.7 section 28.6
- Treat revisioning as a deliberate trade-off: it improves history, rollback, and diagnosis but increases API complexity and storage requirements. section 28.4
