External Restore API Overview

Overview

This document outlines comprehensive API test scenarios for the External Restore functionality in the broker service. All tests are performed directly via API calls against a live or staging environment. Each section describes a specific endpoint, its purpose, and guidance on when and how to use it.

API Endpoints

Base Path:

/byoc/subscriptions/{subscription_id}/dataplanes/{dataplane_id}/engines/{engine_id}

All endpoints listed below are relative to the base path above. Replace the path parameters {subscription_id}, {dataplane_id}, and {engine_id} with the appropriate identifiers for your target environment.

POST /ext-restore — Initiate an External Restore

What is it?

Initiates an external restore operation from a backup image stored in Azure Blob Storage. This endpoint allows you to restore a Db2 database from a backup that was created outside the current system — commonly referred to as an external backup.

Why use it?

• Restore databases from backups taken on different systems or environments.
• Migrate databases from on-premises or other cloud environments to Azure BYOC.
• Recover from disaster scenarios using externally stored backups.
• Test database restores in isolation without affecting production systems.

POST /ext-restore-rollforward — Perform a Rollforward After External Restore

What is it?

Performs a rollforward operation after an external restore has been completed. Rollforward applies transaction logs to bring the database to a specific point in time or to the end of the available logs, completing the recovery sequence.

Why use it?

• Recover a database to a precise point in time following a restore operation.
• Apply transaction logs that were not included in the original backup image.
• Complete a deferred restore process when complete_rollforward was initially set to false.
• Minimise data loss by applying all available archive logs after the base restore.

GET /external-restore-statuses — List All External Restore Statuses

What is it?

Retrieves a list of all external restore operations and their current statuses for a specific Db2 engine. The response includes both in-progress and historical restore records.

Why use it?

• Monitor multiple restore operations that are concurrently in progress.
• Review the history of past restore operations for a given engine.
• Audit restore activities to meet compliance or change-management requirements.
• Troubleshoot failed restore operations by reviewing their recorded status history.

GET /external-restore-status?name={name} — Get Status of a Specific External Restore

What is it?

Retrieves the detailed status of a specific external restore operation identified by its unique name. This endpoint provides granular information about a single restore job, including progress indicators and any error details.

Why use it?

• Check the real-time progress of a specific, named restore operation.
• Retrieve detailed error messages when a restore fails to help with root-cause analysis.
• Verify that a restore has completed successfully before initiating a rollforward.
• Debug issues with individual restore jobs using the detailed status payload.

POST /restore — Perform an Internal Restore

What is it?

Performs an internal restore operation using backups that were created within the current system and are already cataloged in the Db2 backup catalog. This endpoint is the standard path for restoring system-managed backups.

Why use it?

• Restore from backups produced by the system's automated backup process.
• Execute a quick restore without needing to supply external storage credentials.
• Restore to a specific timestamp using a backup that appears in the cataloged backup list.
• Simplify the restore workflow for backups that are fully managed by the system.

GET /backups — List Available Backup Images

What is it?

Retrieves a list of available backup images that are cataloged in the Db2 backup catalog. This endpoint is useful for discovering which backups can be used with the internal restore endpoint.

Why use it?

• Discover available backups before initiating a restore operation.
• Verify backup timestamps for point-in-time recovery planning.
• Review backup metadata — such as size, type, and creation timestamp — to select the appropriate image.
• Plan restore operations by examining all cataloged backup options in one call.