Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Content History

The Content History system in Kinesis API provides version tracking and restoration capabilities for key content types. This feature automatically preserves previous versions of content, allowing administrators to recover from accidental changes, track content evolution, or restore content to a known-good state when needed.

Overview

Content History serves as a version control system for:

  • Data objects (structured content)
  • Routes (API definitions)
  • Blog posts (published articles)

The system automatically captures snapshots of content whenever changes are made, storing these versions in a chronological history that can be browsed and restored when needed.

Key Features

Automatic Version Tracking

  • Seamless Capture: Every update to supported content types automatically creates a history entry
  • Comprehensive Metadata: Each version includes creation timestamp and complete content state
  • Zero Configuration: Works out-of-the-box with no setup required
  • Storage Optimization: Only the last 15 versions are retained to conserve storage space

Version Management

  • Historical Timeline: Browse all previous versions of content by date
  • One-Click Restoration: Restore any previous version with a simple confirmation
  • Safe Restoration: Current version remains available in history if restoration is needed
  • Metadata Retention: All associated data is preserved during restoration

Security and Access Control

  • Root-Only Access: Content history management is restricted to ROOT users
  • Audit Trail: Changes are tracked with timestamps for accountability
  • Non-Destructive: Restoration adds to history rather than erasing it

Supported Content Types

The Content History system currently supports three primary content types:

Data Objects

Complete version history is maintained for data objects, including:

  • All structure values
  • Custom structure values
  • Metadata and configuration

Routes

API route definitions are tracked, preserving:

  • Route configurations
  • Authentication settings
  • Parameters and body definitions
  • Full visual flow definitions

Blog Posts

Blog post versions include:

  • Content body
  • Title, subtitle, and slug
  • Tags and metadata
  • Media references
  • Visibility and publication status

User Permissions

Content History functionality is currently limited to ROOT users only for security reasons:

ROOT Users

  • View content history for all content types
  • Restore any content to previous versions
  • Access the history management interface

Other User Roles

  • No access to content history functionality
  • Cannot view or restore previous versions

Using Content History

The Content History interface is integrated into the edit screens for supported content types:

Content History Interface

Accessing Version History

For ROOT users, a "Restore Previous Version" button appears in the edit interface for:

  1. Data Objects: On the data edit page
  2. Routes: On the route edit page
  3. Blog Posts: On the blog post edit page

Clicking this button opens a modal with a chronological list of previous versions.

Viewing Available Versions

The version history modal displays:

  • Version ID
  • Creation date and time
  • Sorted with newest versions at the top

Restoring a Previous Version

To restore content to a previous version:

  1. Click the "Restore Previous Version" button
  2. Select the desired version from the list
  3. Confirm the restoration in the confirmation dialog
  4. The content will be restored to the selected version
  5. A success message confirms the restoration

The restoration process:

  • Replaces the current content with the selected version
  • Preserves the history, including the version you just replaced
  • Maintains all relationships and references
  • Automatically applies any structure changes

Technical Implementation

Content History leverages several key components:

Storage Mechanism

  • History entries are stored in a dedicated content_history table
  • Each entry contains a snapshot of the entire content state
  • Large content is automatically handled via the blob storage system
  • Content is serialized using a standardized format for consistency

Tracking Algorithm

When content is updated:

  1. The system captures a complete snapshot before changes are applied
  2. The snapshot is stored with metadata including timestamp and content type
  3. Older entries beyond the retention limit are automatically pruned
  4. References to blob storage are properly maintained

Restoration Process

During restoration:

  1. The selected version is deserialized from storage
  2. Current content is completely replaced with the historical version
  3. Any necessary data transformations are applied
  4. The database transaction ensures atomicity
  5. A new history entry is created for the current state (pre-restoration)

Best Practices

For effective use of Content History:

Regular Reviews

  • Periodically review content history for important assets
  • Consider restoration for recovering accidentally deleted content
  • Use history to understand content evolution over time

Before Major Changes

  • Note the timestamp before making significant content changes
  • This helps identify the correct version for restoration if needed
  • Consider creating descriptive commit messages in future versions

When to Restore

Restoration is particularly valuable when:

  • Content was accidentally deleted or corrupted
  • Previous content needs to be referenced or reused
  • Comparing current content with historical versions
  • Undoing changes that didn't meet expectations

Storage Considerations

  • Be aware that only the last 15 versions are retained
  • Plan important content updates accordingly
  • Export critical content before major changes

Future Enhancements

The Content History system will be expanded in future releases:

  • Access for additional user roles with appropriate permissions
  • Descriptive labels for important versions
  • Side-by-side comparison of versions
  • More granular control over retention policies
  • Additional content types support

Troubleshooting

Common Issues

History Not Appearing

  • Verify you have ROOT privileges
  • Check that the content type is supported
  • Ensure content has been modified at least once

Restoration Failed

  • Check that the content still exists
  • Verify database connectivity
  • Ensure sufficient storage space is available

Missing Versions

  • Older versions beyond the 15-version limit are automatically pruned
  • Check if the content has undergone many revisions