--- title: "API usage examples" description: "Aerospike Backup Service (ABS) REST API request and response examples for backups, restores, and configurations." --- # API usage examples > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. Common operations for the Aerospike Backup Service (ABS) REST API, with example requests and responses. See the [REST API specification](https://aerospike.github.io/aerospike-backup-service) 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](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/3.1.0/config-examples). These endpoints use the same ABS authentication and authorization settings as other ABS API endpoints. ### [Trigger an on-demand full backup](https://aerospike.github.io/aerospike-backup-service/#/Backup/scheduleFullBackup) 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. ```http POST BASE_URL/v1/backups/schedule/ROUTINE_NAME?delay=DELAY_MS ``` **Response:** - `202 Accepted` ### [Cancel all jobs for a backup routine](https://aerospike.github.io/aerospike-backup-service/#/Backup/cancelCurrentBackup) Cancels any running full and incremental backups for the specified routine and deletes any partially created backups. Request: - `ROUTINE_NAME`: Backup routine name. ```http POST BASE_URL/v1/backups/cancel/ROUTINE_NAME ``` **Response:** - `202 Accepted` ### [Get information about a running backup](https://aerospike.github.io/aerospike-backup-service/#/Backup/getCurrentBackup) 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. ```http GET BASE_URL/v1/backups/currentBackup/ROUTINE_NAME ``` **Response:** Example The following example response shows two backups in progress, one full and one incremental. ```json { "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 } }, "next-full": "2024-01-02T00:00:00Z", "next-incremental": "2024-01-01T13:00:00Z" } ``` ### [Retrieve full backup list](https://aerospike.github.io/aerospike-backup-service/#/Backup/getFullBackups) 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. ```http GET BASE_URL/v1/backups/full ``` **Response:** Example ```json { "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](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/3.1.0/change-storage) for more information. ::: ## Restore Use restore endpoints to recover data from a backup. You can restore from a specific backup path, or restore a backup routine to a timestamp, 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](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreFull) The `destination` field specifies where to restore data. It can be one of the clusters from [Get cluster configuration](#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](#retrieve-full-backup-list). Copy the `key` field from the backup into the `backup-data-path` field. Request: ```http POST BASE_URL/v1/restore/full ``` Request body: ```json { "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`](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreStatus). ```json 123456789 ``` ### [Restore using routine name and timestamp](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreTimestamp) Restores the most recent full backup before the given timestamp and then applies all subsequent incremental backups up to that timestamp. Required fields: - `routine`: Backup routine name from the ABS configuration. - `time`: Target epoch timestamp in milliseconds. ABS restores the closest backup state before this time. - `destination` or `destination-name`: Aerospike cluster to restore into. Use `destination` for an inline cluster, or `destination-name` to reference a cluster already defined in the ABS configuration. These fields are mutually exclusive. Optional: `policy` for restore policy overrides, `disable-reordering` set to `true` to disable reverse-order optimization for incremental backups, and `secret-agent` or `secret-agent-name` for decrypting backup files or resolving credentials. Request: ```http POST BASE_URL/v1/restore/timestamp ``` Request body with an inline destination: ```json { "destination": { "seed-nodes": [ { "host-name": "localhost", "port": 3000 } ], "credentials": { "user": "tester", "password": "psw" } }, "policy": { "no-generation": true }, "routine": "daily-backup", "time": 1739538000000 } ``` Request body that references a configured cluster by name: ```json { "destination-name": "absDefaultCluster", "routine": "daily-backup", "time": 1739538000000 } ``` The response is a job ID. You can get job status with the endpoint [`GET BASE_URL/v1/restore/status/:JOB_ID`](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreStatus). ```json 123456789 ``` ### [Restore job status](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreStatus) Returns the status of a restore job. Status values are `Running`, `Done`, `Failed`, and `Cancelled`. Request: ```http GET BASE_URL/v1/restore/status/JOB_ID ``` **Response:** Example ```json { "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](https://aerospike.github.io/aerospike-backup-service/#/Configuration/readAllClusters) Returns the configuration files of existing clusters, including the default cluster setup with seed nodes and credentials. Request: ```http GET BASE_URL/v1/config/clusters ``` **Response:** Example ```json { "absDefaultCluster": { "seed-nodes": [ { "host-name": "host.docker.internal", "port": 3000 } ], "credentials": { "user": "tester", "password": "psw" } } } ``` ### [Get routine configuration](https://aerospike.github.io/aerospike-backup-service/#/Configuration/readRoutines) Retrieves all configured backup routines. Request: ```http GET BASE_URL/v1/config/routines ``` **Response:** Example ```json { "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](https://aerospike.github.io/aerospike-backup-service/#/Configuration/readAllStorage) Returns all the configured storage endpoints, including cloud storage endpoint information such as region and path, if applicable. Request: ```http GET BASE_URL/v1/config/storage ``` **Response:** Example ```json { "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](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/3.1.0/monitoring) for details on available metrics. ### [Get service version](https://aerospike.github.io/aerospike-backup-service/#/System/version) Returns version information about the running Aerospike Backup Service instance. Request: ```http GET {{BASE_URL}}/version ``` ::: note The endpoint is at the root path, not under `/v1`. ::: **Response:** Example ```text v3.1.0 ```