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

Trigger a backup routine

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

Request: Provide the routine name and an optional delay in milliseconds before the backup starts.

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

If the request is accepted, the server responds with HTTP 202 Accepted.

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:

POST BASE_URL/v1/backups/cancel/ROUTINE_NAME

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:

Provide the name of the backup routine you want to examine in your request.

GET BASE_URL/v1/backups/currentBackup/ROUTINE_NAME

Response:

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
        }
    }
}

Retrieve full backup list

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

Request:

GET BASE_URL/v1/backups/full

Response:

{
    "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

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.

Response:

123456789

Restore using routine name and timestamp

This option restores the most recent full backup for the given timestamp and then applies all subsequent incremental backups up to that timestamp. In this example, the destination and policy fields are the same as in the previous example.

Request:

POST BASE_URL/v1/restore/timestamp

Request body:

{
  "destination": {
    "seed-nodes": [
      {
        "host-name": "localhost",
        "port": 3000
      }
    ],
    "credentials": {
      "user": "tester",
      "password": "psw"
    }
  },
  "policy": {
    "no-generation": true
  },
  "routine": "routine1",
  "time": 1710671632452
}

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

Response:

123456789

Show all restore jobs

Lists all restore jobs, with optional filtering by time range and status.

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. The possible statuses are Running, Done, Failed, and Cancelled. Use the ! prefix to exclude one or more statuses, such as !Failed,Cancelled.

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

This section details how to fetch configurations for clusters, policies, and storage options. This information is useful for setting up or verifying the configuration of your system.

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:

{
  "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:

{
  "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:

{
    "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"
        }
    }
}