API Usage Examples

Use this section as a guide to get familiar with the most common commands performed with the Aerospike Backup Service (ABS) REST API. The full schemas for the most recent ABS release are published here: REST API Specification

Read configurations

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

Get cluster configuration

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

Request:

GET {{baseUrl}}/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 {{baseUrl}}/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, if applicable, cloud storage endpoint information such as region and path.

Request:

GET {{baseUrl}}/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"
        }
    }
}

Retrieve full backup list

Provides a list of backups for each configured routine, including details such as creation time, namespace, and storage location.

Request:

GET {{baseUrl}}/v1/backups/full

Response:

{
    "routine1": [
        {
            "created": "2024-03-14T13:13:28.96962301Z",
            "from": "0001-01-01T00:00:00Z",
            "namespace": "source-ns7",
            "byte-count": 48,
            "file-count": 1,
            "key":"minioRoutine/backup/1718209702821/data/test"
            "storage": {
                "s3-storage": {
                    "bucket": "as-backup-bucket",
                    "path": "backups",
                    "s3-region": "eu-central-1"
                }
            }
        }
    ],
    "routine2": [
        {
            "created": "2024-03-14T13:13:29.105744927Z",
            "from": "0001-01-01T00:00:00Z",
            "namespace": "source-ns8",
            "byte-count": 48,
            "file-count": 1,
            "key": "localStorage/filterBySetAndBin/backup/source-ns8",
            "storage": {
                "s3-storage": {
                    "bucket": "as-backup-bucket",
                    "path": "backups",
                    "s3-region": "eu-central-1"
                }
            }
            ]
        }

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 {{baseUrl}}/v1/backups/currentBackup/ROUTINE_NAME

Response:

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

{
    "full": {
        "done-records": 50,
        "estimated-end-time": "2024-01-02T15:10:05Z07:00",
        "percentage-done": 50,
        "start-time": "2024-01-02T15:04:05Z07:00",
        "total-records": 100
    },
    "incremental": {
        "done-records": 50,
        "estimated-end-time": "2024-01-02T15:10:05Z07:00",
        "percentage-done": 50,
        "start-time": "2024-01-02T15:04:05Z07:00",
        "total-records": 100
    }
}

Restore backup (direct restoration)

Direct restore using a specific backup

The destination field says where to restore to. It can be one of the clusters from the Get Cluster Configuration section or any other Aerospike 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 is exactly the same as the storage field of a backup returned from the Full Backup List, The key field from the backup should go into the backup-data-path field.

Request:

POST {{baseUrl}}/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 {{baseUrl}}/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 {{baseUrl}}/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 {{baseUrl}}/v1/restore/status/:JOB_ID.

Response:

123456789