DocumentationServerSnapshots

Snapshots

Overview

Jspreadsheet Server provides version control through snapshots, which let users create and restore spreadsheet versions. This feature is limited to spreadsheet owners, who can manage snapshots via the interface or automate their creation using API calls at chosen intervals.

Requirements
Requires the Jspreadsheet Server API Extension and AWS S3.

Frontend

Spreadsheet owners can use the interface to create new snapshots or restore previous versions.

Server

Setup

Snapshots are compressed and stored in your AWS S3 bucket. Each snapshot is the full spreadsheet configuration, zipped and saved under the key <guid>/snapshots/<YYYYMMDDHHMMSS>; the timestamp becomes the snapshot's versionId. Configure the API extension with your S3 credentials, because without an S3 configuration the snapshot routes respond with 500 S3 not defined.

const server = require('@jspreadsheet/server');
const adapter = require('@jspreadsheet/server-mongodb');
const api = require('@jspreadsheet/server-api');

// Load from ENV
require('dotenv').config();

// Jspreadsheet license
const license = {
    clientId: process.env.JSS_CLIENT,
    licenseKey: process.env.JSS_LICENSE
};

// Connect API to S3
api({
    s3: {
        key: process.env.AWS_S3_KEY,
        secret: process.env.AWS_S3_SECRET,
        bucket: process.env.AWS_BUCKET,
        region: process.env.AWS_S3_REGION,
        url: process.env.AWS_S3_URL,
    }
});

Access Control

Every snapshot route first checks the server's isOwner hook and returns 403 Forbidden for non-owners. Creating, restoring and deleting snapshots additionally pass through your beforeChange hook with the methods createSnapshot, restoreSnapshot and deleteSnapshot, so you can apply further rules there; in the reference wiring all three are owner-only methods.

History API

The API can be used to automate snapshot creation based on custom rules.

Routes

Restore Behavior

Before a restore is applied, the server automatically creates a snapshot of the current state, so the pre-restore version is never lost. The document is then replaced with the snapshot contents: if your server configuration defines a replace handler it is used; otherwise the document is destroyed and re-created from the snapshot through your destroy and create handlers.

Example

Retrieve a list of all spreadsheet snapshots over the REST API. This route is owner-only:

const baseUrl = 'https://your-server.example.com/api';
const guid = '79b45919-c751-4e2b-a49a-6c1286e2fc03';
const headers = { 'Authorization': `Bearer ${token}` };

const snapshots = await (await fetch(`${baseUrl}/${guid}/history`, { headers })).json();
console.log(snapshots);

More Information

For additional details on the History API, refer to the documentation.

REST API routes