Examine Backed-Up Data

The Backup Service REST API allows the examination of instances of a specified document, within a subset of backups from a specified active, imported, or archived repository.

HTTP Method and URI

POST /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-id>/examine

Description

Retrieves instances of a document from a subset of backups within a repository. The repository can be active, imported, or archived. The document-key and bucket (optionally with scope and collection) must be specified as a JSON payload.

Curl Syntax

curl -X POST http://<backup-node-ip-address-or-domain-name>:8097/cluster/self\
/repository/< "active" | "imported" | "archived" >/<repository-id>/examine \
  -u <username>:<password>
  -d <document-search-specification>

The username and password must identify an administrator with the Full Admin role. The repository-id must be the name of a repository that is active, imported, or archived, depending on the specification made by the preceding path-parameter. The document-search-specification must be a JSON document that specifies the following:

The key of a document.
A data path. The bucket, scope, and collection within which the document resides. The names must be specified in order of containment, period-separated: for example, travel-sample._default._default.

Syntactically therefore, the document-search-specification should be as follows:

{
  "key": <document-key>,
  "data_path": < bucket-name.scope-name.collection-name >
}

Responses

If successful, the call returns 200 OK, and a series of documents, each being a backed up instance of that sought for by its key. If the specified repository cannot be found, 404 Object No Found is returned. If an internal error prevents successful execution, 500 is returned. Failure to authenticate returns 401 Unauthorized. An incorrectly specified URI returns 404 Object Not Found.

Example

The following example is used to examine instances of the document whose key is airline_10, within the default scope and collection of the travel-sample bucket, in the active repository hourlyBackupRepo.

curl -v -X POST http://127.0.0.1:8097/api/v1/cluster/self/\
repository/active/hourlyBackupRepo/examine \
-u Administrator:password \
-d '{"key": "airline_10","data_path":"travel-sample._default._default"}'

On success, the call returns the following:

{
  "backup": "2020-09-11T16_30_10.894277+01_00",
  "sequence_number": 500,
  "key": "airline_10",
  "value": {
    "callsign": "MILE-AIR",
    "country": "United States",
    "iata": "Q5",
    "icao": "MLA",
    "id": 10,
    "name": "40-Mile Air",
    "type": "airline"
  },
  "metadata": {
    "flags": 33554438,
    "expiry": 0,
    "locktime": 0,
    "cas": 1598358036122239000,
    "revseqno": 2,
    "datatype": 3
  },
  "deleted": false
}
{
  "backup": "2020-09-14T17_00_55.976325+01_00",
  "sequence_number": 501,
  "key": "airline_10",
  "value": {
    "callsign": "MILE-AIR",
    "country": "United States",
    "iata": "Q6",
    "icao": "MLA",
    "id": 11,
    "name": "40-Mile Air",
    "type": "airline"
  },
  "metadata": {
    "flags": 33554438,
    "expiry": 0,
    "locktime": 0,
    "cas": 1600097937324376000,
    "revseqno": 3,
    "datatype": 3
  },
  "deleted": false
}

Thus, each object returns contains the id of the backup within which the document-instance resides, the sequence number of the document-instance, and the data and metadata values of the instance.