API usage examples

Common operations for the Aerospike Backup Service (ABS) REST API, with example requests and responses. See the REST API specification for request and response schemas.

Backup

Use backup endpoints to trigger scheduled or on-demand backup operations for your routines, monitor backups that are currently running, and cancel jobs if needed. Routines themselves are defined in your configuration file.

These endpoints use the same ABS authentication and authorization settings as other ABS API endpoints.

Trigger an on-demand full backup

Starts a full backup for the specified routine, ignoring any configured schedule.

Request:

• ROUTINE_NAME: Backup routine name.
• delay (optional): Delay in milliseconds before the backup starts.

POST BASE_URL/v1/backups/full/ROUTINE_NAME?delay=DELAY_MS

Response:

• 202 Accepted

Trigger an on-demand incremental backup

Starts an incremental backup for the specified routine, ignoring any configured schedule. The routine determines which namespace and optional set filters are backed up.

Request:

• ROUTINE_NAME: Backup routine name.
• delay (optional): Delay in milliseconds before the backup starts.

POST BASE_URL/v1/backups/incremental/ROUTINE_NAME

Example with 1000 ms delay:

POST BASE_URL/v1/backups/incremental/ROUTINE_NAME?delay=1000

Response:

• 202 Accepted

Trigger a backup routine (deprecated)

POST /v1/backups/schedule/ROUTINE_NAME is deprecated, but still supported for backward compatibility. It triggers a full backup and accepts the same optional delay query parameter.

Cancel all jobs for a backup routine

Cancels any running full and incremental backups for the specified routine and deletes any partially created backups.

Request:

• ROUTINE_NAME: Backup routine name.

POST BASE_URL/v1/backups/cancel/ROUTINE_NAME

Response:

• 202 Accepted

Get information about a running backup

Shows information about currently running backups for a specific backup routine, including number of records completed, start time, progress toward completion, and estimated end time.

Request:

• ROUTINE_NAME: Backup routine name.

GET BASE_URL/v1/backups/currentBackup/ROUTINE_NAME

Response:

Example

The following example response shows two backups in progress, one full and one incremental.

{
    "full": {
        "total-records": 100000,
        "done-records": 50000,
        "start-time": "2024-01-01T12:00:00Z",
        "percentage-done": 50,
        "estimated-end-time": "2024-01-01T13:00:00Z",
        "metrics": {
            "records-per-second": 1000,
            "kilobytes-per-second": 30000,
            "pipeline": 0
        }
    },
    "incremental": {
        "total-records": 20000,
        "done-records": 15000,
        "start-time": "2024-01-01T12:30:00Z",
        "percentage-done": 75,
        "estimated-end-time": "2024-01-01T12:40:00Z",
        "metrics": {
            "records-per-second": 1000,
            "kilobytes-per-second": 30000,
            "pipeline": 0
        }
    }
}

Retrieve full backup list

Lists backups for each configured routine, including details such as creation time, namespace, and storage location.

Request:

• from (optional): Lower bound timestamp filter in milliseconds since epoch.
• to (optional): Upper bound timestamp filter in milliseconds since epoch.

GET BASE_URL/v1/backups/full

Response:

Example

{
    "routine1": [
        {
            "created": "2024-01-01T12:00:00Z",
            "timestamp": 1704110400000,
            "finished": "2024-01-01T12:05:00Z",
            "duration": 300,
            "from": "0001-01-01T00:00:00Z",
            "namespace": "source-ns1",
            "record-count": 42,
            "byte-count": 480000,
            "file-count": 1,
            "secondary-index-count": 5,
            "udf-count": 1,
            "key": "routine1/backup/1704110400000/source-ns1",
            "storage": {
                "s3-storage": {
                    "bucket": "as-backup-bucket",
                    "path": "backups",
                    "s3-region": "eu-central-1"
                }
            },
            "compression": "ZSTD",
            "encryption": "NONE"
        }
    ]
}

Note

This endpoint lists only the backups that reside in the storage location configured for the routine at the moment you call the API. It cannot access historical backups in different storage locations.

If you have changed the storage field in a routine and there has not yet been a full backup in the new storage location, the response can appear empty.

To inspect historical backups, temporarily modify the routine back to its previous storage location or browse the old bucket directly.

See Change backup storage destination for more information.

Restore

Use restore endpoints to recover data from a backup. You can restore from a specific backup path or from a point in time, which automatically combines the most recent full backup with any subsequent incremental backups. Restores run asynchronously and return a job ID that you can use to track progress.

Direct restore using a specific backup

The destination field specifies where to restore data. It can be one of the clusters from Get cluster configuration or any other Aerospike Database cluster.

This request restores a backup from a specified path to a designated destination. The no-generation parameter allows overwriting of existing keys if set to true.

The source section matches the storage field of a backup returned from Retrieve full backup list. Copy the key field from the backup into the backup-data-path field.

Request:

POST BASE_URL/v1/restore/full

Request body:

{
    "destination": {
        "seed-nodes": [
            {
                "host-name": "localhost",
                "port": 3000
            }
        ],
        "credentials": {
            "user": "user",
            "password": "password"
        }
    },
    "policy": {
        "no-generation": true
    },
    "source": {
        "s3-storage": {
            "bucket": "as-backup-bucket",
            "path": "backups",
            "s3-region": "eu-central-1"
        }
    },
    "backup-data-path": "routine1/backup/1704110400000/source-ns1"
}

The response is a job ID. You can get the status of this job with the endpoint GET BASE_URL/v1/restore/status/:JOB_ID.

123456789

Restore using routine name and timestamp

Restores the most recent full backup before the given timestamp and then applies all subsequent incremental backups up to that timestamp.

In ABS 3.6.1 and later, you can override storage, destination, and Secret Agent settings in the request body. If an override is omitted, ABS falls back to the matching field from the local routine configuration.

Required fields

• routine: Backup routine name. ABS uses this name to locate the backup chain in storage, even when the routine is not configured locally.
• time: Target epoch timestamp in milliseconds. ABS restores the closest backup state before this time.

Optional override fields

• Storage: source or source-name. Mutually exclusive.
• Destination: destination or destination-name. Mutually exclusive.
• Secret Agent: secret-agent or secret-agent-name at the top level for backup decryption. Destination credentials can use an inline secret-agent block to fetch database passwords from the Secret Agent.
• Password references: Use the format secrets:RESOURCE_LABEL:KEY, where RESOURCE_LABEL is an arbitrary label you define when storing secrets in the agent.
• Policy: policy for restore policy overrides.
• Incremental order: disable-reordering set to true disables reverse-order optimization for incremental backups.

When both storage and destination are provided, the routine does not need to exist in the ABS configuration file. If you override only one side, the routine must exist locally so ABS can resolve the other value.

Request:

POST BASE_URL/v1/restore/timestamp

Standard restore with a locally configured routine:

{
  "routine": "daily-backup",
  "time": 1739538000000
}

Partial override. Read from the routine’s storage, but restore to a different cluster:

{
  "routine": "daily-backup",
  "time": 1739538000000,
  "destination-name": "staging-cluster"
}

Cross-region restore. The DR ABS instance does not define daily-backup locally, but both storage and destination are provided:

{
  "routine": "daily-backup",
  "time": 1739538000000,
  "source": {
    "s3-storage": {
      "bucket": "dr-backup-bucket-us-west",
      "path": "backups",
      "s3-region": "us-west-2"
    }
  },
  "destination-name": "local-dr-cluster"
}

Cross-region restore with Secret Agents. The top-level secret-agent-name decrypts backup files. The inline secret-agent under credentials fetches the destination database password:

{
  "routine": "cross-region-routine",
  "time": 1739538000000,
  "source": {
    "s3-storage": {
      "bucket": "dr-backup-bucket-us-west",
      "path": "backups",
      "s3-region": "us-west-2"
    }
  },
  "secret-agent-name": "my-local-decryption-agent",
  "destination": {
    "seed-nodes": [
      { "host-name": "10.0.0.5", "port": 3000 }
    ],
    "credentials": {
      "user": "admin",
      "password": "secrets:cluster-creds:password",
      "secret-agent": {
        "address": "127.0.0.1",
        "port": 3005,
        "connection-type": "tcp"
      }
    }
  }
}

The response is a job ID. You can get job status with the endpoint GET BASE_URL/v1/restore/status/:JOB_ID.

123456789

Show all restore jobs

Lists all restore jobs, with optional filtering by time range and status. In ABS 3.6.1 and later, restore job responses use the lowercase status values running, success, failure, and canceled.

Request:

GET BASE_URL/v1/restore/jobs?from=FROM&to=TO&status=STATUS

• from: Lower bound timestamp filter in milliseconds since epoch.
• to: Upper bound timestamp filter in milliseconds since epoch.
• status: Comma-separated status filter.
  • Canonical statuses are running, success, failure, and canceled.
  • Matching is case-insensitive. The legacy aliases done and failed map to success and failure.
  • Use the ! prefix to exclude one or more statuses, such as !failure,canceled.

Response:

Example

{
    "12345678": {
        "read-records": 100000,
        "total-bytes": 30000000,
        "expired-records": 0,
        "skipped-records": 0,
        "ignored-records": 0,
        "inserted-records": 50000,
        "existed-records": 0,
        "fresher-records": 0,
        "index-count": 4,
        "udf-count": 1,
        "errors-in-doubt": 0,
        "current-job": {
            "total-records": 100000,
            "done-records": 50000,
            "start-time": "2024-01-01T12:00:00Z",
            "percentage-done": 50,
            "estimated-end-time": "2024-01-01T13:00:00Z",
            "metrics": {
                "records-per-second": 1000,
                "kilobytes-per-second": 30000,
                "pipeline": 0
            }
        },
        "status": "running"
    }
}

Read configurations

Verify settings or debug configuration issues with the following endpoints. They retrieve the service’s current configuration, including cluster definitions, backup routines, and storage destinations.

Get cluster configuration

Returns the configuration files of existing clusters, including the default cluster setup with seed nodes and credentials.

Request:

GET BASE_URL/v1/config/clusters

Response:

Example

{
  "absDefaultCluster": {
    "seed-nodes": [
      {
        "host-name": "host.docker.internal",
        "port": 3000
      }
    ],
    "credentials": {
      "user": "tester",
      "password": "psw"
    }
  }
}

Get routine configuration

Retrieves all configured backup routines.

Request:

GET BASE_URL/v1/config/routines

Response:

Example

{
  "routine1": {
    "backup-policy": "defaultPolicy",
    "source-cluster": "absDefaultCluster",
    "storage": "local",
    "interval-cron": "@yearly",
    "namespaces": ["source-ns7"]
  },
  "routine2": {
    "backup-policy": "defaultPolicy",
    "source-cluster": "absDefaultCluster",
    "storage": "local",
    "interval-cron": "@yearly",
    "namespaces": ["source-ns8"],
    "set-list": ["backupSet"],
    "bin-list": ["backupBin"]
  }
}

Get storage configuration

Returns all the configured storage endpoints, including cloud storage endpoint information such as region and path, if applicable.

Request:

GET BASE_URL/v1/config/storage

Response:

Example

{
    "local": {
        "local-storage": {
            "path": "./localStorage"
        }
    },
    "minio": {
        "s3-storage": {
            "path": "storage1",
            "bucket": "as-backup-bucket",
            "s3-region": "eu-central-1",
            "s3-profile": "minio",
            "s3-endpoint-override": "http://host.docker.internal:9000"
        }
    }
}

System

Retrieve operational information about the service with the following system endpoints. Use these to perform health probes, check versions, and integrate with monitoring tools like Prometheus. See Monitoring for details on available metrics.

Get service version

Returns version information about the running Aerospike Backup Service instance.

Request:

GET {{BASE_URL}}/version

Note

The endpoint is at the root path, not under /v1.

Response:

Example

{
  "version": "3.6.1",
  "build-time": "BUILD_TIMESTAMP",
  "commit": "COMMIT_SHA"
}