Skip to main content
Loading

API Usage Examples

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

Service configuration file​

The following is an example backup configuration file illustrating the basic requirements for a backup configuration.

View full configuration file
aerospike-clusters:
  absDefaultCluster:
    seed-nodes:
      - host-name: "localhost"
        port: 3000
    credentials:
      user: "tester"
      password: "psw"
    max-parallel-scans: 8
    
storage:
  # Example 1: Local Storage
  storage1:
    local-storage:
      path: /local/backups

    # Example 2: S3 Storage
    storage2:
      s3-storage:
        bucket: my-backup-bucket
        path: backups
        s3-profile: default
        s3-region: eu-central-1

    # Example 3: Azure Storage
    storage3:
      azure-storage:
        account-name: my-storage-account
        account-key: my-secret-key
        container-name: my-container
        endpoint: 'https://my-storage-account.blob.core.windows.net'
        path: backups

    # Example 4: GCP Storage
    storage4:
      gcp-storage:
        bucket-name: my-gcp-bucket
        key-file: /path/to/service-account-key.json
        endpoint: 'https://storage.googleapis.com'
        path: backups

backup-policies:
  keepFilesPolicy:
    parallel: 5

backup-routines:
  testRoutine:
    interval-cron: "@weekly"
    incr-interval-cron: "@hourly"
    source-cluster: absDefaultCluster # one of predefined clusters
    storage: storage1 #can be any of predefined storage
    namespaces: [ "source-ns1" ]
    backup-policy: keepFilesPolicy # one of predefined policies

service:
  logger:
    file-writer:
      filename: "log/backup-service.log"
    level: INFO

Configuration file components​

aerospike-clusters​

This example configuration connects to the Aerospike Database cluster, absDefaultCluster. The seed-nodes parameter defines the host and port for the Aerospike cluster on the network. The credentials parameter passes a plain text username and password so that ABS can access the database. max-parallel-scans sets a global limit on the number of concurrent backups.

aerospike-clusters:
  absDefaultCluster:
    seed-nodes:
      - host-name: "localhost"
        port: 3000
    credentials:
      user: "tester"
      password: "psw"
    max-parallel-scans: 8

storage​

The storage section sets up four different storage destinations: local, S3, Azure, and GCP. Each one has a separate label, here storage1, storage2, and so on. You can set up as many or as few destinations as you want in your own configuration. Note the specific authentication requirements for the different cloud storage providers.

storage:
  # Example 1: Local Storage
    storage1:
      local-storage:
        path: /local/backups
        
    # Example 2: S3 Storage
    storage2:
      s3-storage:
        bucket: my-backup-bucket
        path: backups
        s3-profile: default
        s3-region: eu-central-1

    # Example 3: Azure Storage
    storage3:
      azure-storage:
        account-name: my-storage-account
        account-key: my-secret-key
        container-name: my-container
        endpoint: 'https://my-storage-account.blob.core.windows.net'
        path: backups

    # Example 4: GCP Storage
    storage4:
      gcp-storage:
        bucket-name: my-gcp-bucket
        key-file: /path/to/service-account-key.json
        endpoint: 'https://storage.googleapis.com'
        path: backups

backup-policies​

The backup-policies section in this example defines a policy called keepFilesPolicy. By only specifying two parameters, it accepts default values for all others. With parallel, it specifies the number of parallel reader threads that read Aerospike partitions. remove-files is set to KeepAll, meaning any existing files in the backup directory are kept for each backup rather than being overwritten.

backup-policies:
  keepFilesPolicy:
    parallel: 5

backup-routines​

The backup-routines section schedules one or more routines to run from specified sources at specified intervals. In this example, the routine testRoutine backs up the "source-ns1" namespace, in a defined source cluster absDefaultCluster, to the storage destination storage1, following the rules laid out in keepFilesPolicy. This routine runs weekly for full backups and hourly for incremental backups. 

backup-routines:
  testRoutine:
    interval-cron: "@weekly"
    incr-interval-cron: "@hourly"
    source-cluster: absDefaultCluster 
    storage: storage1 
    namespaces: [ "source-ns1" ]
    backup-policy: keepFilesPolicy

service​

service:
  logger:
    file-writer:
      filename: "log/backup-service.log"
    level: INFO

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": "keepFilesPolicy",
    "source-cluster": "absDefaultCluster",
    "storage": "local",
    "interval-cron": "@yearly",
    "namespaces": ["source-ns7"]
  },
  "routine2": {
    "backup-policy": "removeFilesPolicy",
    "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": "s3://as-backup-bucket/storage1/minio/backup/1710422008983/source-ns4"
    }
  ],
  "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"
    }
  ]
}

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": "tester",
      "password": "psw"
    }
  },
  "policy": {
    "no-generation": "true"
  },
    "source": {
        "s3-storage" :{
            "path": "storage1",
            "bucket": "as-backup-bucket",
            "s3-region": "eu-central-1",
            "s3-profile": "minio",
            "s3-endpoint-override": "http://host.docker.internal:9000"
        },
        "backup-data-path": "minio/backup/1710422008983/source-ns4"
    }
}

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