This chapter covers
- How to safely store multiple revisions of a single resource as it changes over time
- How to identify individual revisions
- Strategies for creating revisions, either implicitly or explicitly
- How to list the available revisions and retrieve specific revisions
- How restoration to previous revisions works
- What to do about child resources of revisable resources
Though resources change over time, we typically discard any changes that might have occurred in the past. In other words, we only ever store what the resource looks like right now and completely ignore how the resource looked before changes were made. This pattern provides a framework by which we can keep track of multiple revisions of a single resource over time, thereby preserving history and enabling advanced functionality such as rolling back to a previous revision.
So far, all of our interactions with resources in an API have focused exclusively on the present state of the resource and ignored previous states. While we do occasionally consider topics like consistency (e.g., when we looked at what happens as resources change while paginating through a list), there’s always been a big assumption about resources: they only exist at a single point in time, and that time is right now.