Smart Cache Graph - Backup API

Introduction

This API lets you manage backups of datasets through a simple set of HTTP endpoints. You can:

  • Create backups of one or all datasets
  • View existing backups
  • Restore backups
  • Delete backups
  • Validate backups using SHACL
  • View validation reports

This API is ideal for automated workflows, scheduled backups, or manual data protection and recovery tasks.

To enable backups the environment variable ENABLE_BACKUPS must be set to true.

The API supports authentication via JWT tokens.

🔑 Authentication

You must be authenticated to use the API.

  • Bearer Token (JWT): Include a standard Authorization: Bearer <your-jwt> header.

🔐 Encryption

Backup files can be automatically encrypted on creation using PGP to provide more secure storage and transportation. When encryption is enabled, each backup is compressed into a single zip file which is then encrypted using the public key and stored with a .zip.enc suffix. The backup is automatically decrypted during restoration using the private key and passphrase.

Encryption applies to backups created after it has been enabled. Existing unencrypted backups can still be restored. Encrypted backups can only be restored while the matching key pair and passphrase are configured, so make sure you keep a secure copy of them elsewhere. If they are lost, the encrypted backups cannot be recovered.

Configuration

To make use of the encryption it is necessary to provide a PGP key pair and passphrase using the following environment variables:

  • BACKUPS_PRIVATE_KEY_URL - the URL of the private key file, for example file:///tmp/private.asc
  • BACKUPS_PUBLIC_KEY_URL - the URL of the public key file, for example file:///tmp/public.asc
  • BACKUPS_PASSKEY - the passphrase used when creating the key

If these environment variables are not set, or one of them is missing, encryption will not be applied. A warning message is shown in the application log files if encryption has not been enabled. If the keys are set but cannot be read, an error is logged and backups are created without encryption, so check the logs after start-up.

Deploying with the Smart Cache Graph Helm chart

When deploying with the Helm chart you do not need to create the keys yourself. Create a Kubernetes secret containing a single key called passphrase, then set:

graph:
  enableBackupEncryption: true
  backupEncryption:
    existingSecret: my-backup-encryption-secret

The chart sets ENABLE_BACKUPS, BACKUPS_PRIVATE_KEY_URL and BACKUPS_PUBLIC_KEY_URL (by default file:///fuseki/backups/keys/private.asc and file:///fuseki/backups/keys/public.asc) and supplies the passphrase as BACKUPS_PASSKEY. An init container generates an RSA 4096 key pair on the backups volume the first time it runs.

On later start-ups the init container checks that the passphrase can unlock the existing private key, and fails if it cannot. Do not change the passphrase in the secret after the keys have been generated. Deleting the key files regenerates the keys but makes any existing encrypted backups inaccessible.

Creating a PGP key pair manually

If you are not using the Helm chart and need to create a PGP key pair this can be done as follows:

gpg --full-generate-key

Select the default or other appropriate options and choose a passphrase - this will need to be set as the value of the BACKUPS_PASSKEY environment variable. Then list the public keys:

gpg --list-keys --keyid-format=long

Copy the key ID for the public key you just created, e.g. F2C0B93297F09448, then export the key to a file:

gpg --armor --export F2C0B93297F09448 > public.asc

Do the same for the private key, first obtaining the private key ID:

gpg --list-secret-keys --keyid-format=long

Then write this to a file as well:

gpg --armor --export-secret-keys F2C0B93297F09448 > private.asc

🛠️ Key Operations

✅ 1. Create a Backup (single dataset)

Endpoint: POST /backups/create/{datasetName}

Purpose: Back up a specific dataset.

Parameters:

  • datasetName (required): Name of the dataset to back up.
  • description (optional): A short note like "Daily backup 12th June 2025".

Response: The numerical ID and details of the freshly generated backup.

Example:

curl -X POST https://telicent.core.domain/api/sparql/backups/create/my-dataset \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>"

✅ 2. Create a Backup (all datasets)

Endpoint: POST /backups/create/

Purpose: Back up all available datasets.

Response: The numerical ID and details of the freshly generated backup(s).

Example:

curl -X POST https://telicent.core.domain/api/sparql/backups/create/

📋 3. List Backups

Endpoint: GET /backups/list

Purpose: Returns a list of all available backup entries and their details.

Response: A JSON list of backup details, including but not limited to:

  • Numerical ID
  • Description (if available)
  • Date
  • Created by User

Example:

curl https://telicent.core.domain/api/sparql/backups/list

♻️ 4. Restore a Backup

Endpoint:

POST /backups/restore/{restoreId}

POST /backups/restore/{restoreId}/{datasetName}

Purpose: Restore data from a backup using its ID.

Parameters:

  • restoreId (required): The numerical ID of the backup to restore.
  • datasetName (optional): Specific dataset for a targeted partial restore.

Response: The details of the restoration.

Example:

curl -X POST https://telicent.core.domain/api/sparql/backups/restore/17

🗑️ 5. Delete a Backup

Endpoint: POST /backups/delete/{deleteId}

Purpose: Permanently remove a backup.

Parameters:

  • deleteId (required): The numerical ID of the backup to delete.

Response: Confirmation of the deleted backup.

Example:

curl -X POST https://telicent.core.domain/api/sparql/backups/delete/abc123

🔍 6. Validate a Backup Using SHACL

There are two ways to validate:

a) Entire Backup

Endpoint: POST /backups/validate/{backupId}

Purpose: Run a SHACL validation on a whole backup.

Parameters:

  • backupId (required)

Response: The results of the validation.

Example:

curl -X POST https://telicent.core.domain/api/sparql/backups/validate/abc123 \
     -H "Content-Type: application/json" \
     -d '{ "shapesGraph": "..." }'

b) Specific Dataset in a Backup

Endpoint: POST /backups/validate/{backupId}/{datasetName}

Purpose: Validate one dataset within a backup using SHACL.

Response: The results of the validation.

Example:

curl -X POST https://telicent.core.domain/api/sparql/backups/validate/abc123/my-dataset \
     -H "Content-Type: application/json" \
     -d '{ "shapesGraph": "..." }'

📄 7. View Validation Report

Endpoint: GET /backups/report/{backupId}/{datasetName}

Purpose: Fetch the SHACL validation results for a specific dataset within a backup. Assuming the validation has been requested (via the validation endpoint above)

Response: The results of the requested SHACL validation.

Example:

curl https://telicent.core.domain/api/sparql/backups/report/abc123/my-dataset

More Details

For a more in-depth description of the actions above please read the accompanying section of the getting started guide here.

[EARLY DRAFT RELEASE] Copyright 2020-2026 Telicent Limited. All rights reserved