HTTP interface for Hot Backups
The HTTP API for Hot Backups lets you manage incremental, zero-downtime data backups
ArangoDB Enterprise Edition
Hot Backups are near instantaneous consistent snapshots of an
entire ArangoDB deployment. This includes all databases, collections,
indexes, Views, graphs, and users at any given time.
For creations a label may be specified, which if omitted
is replaced with a generated UUID. This label is then combined with a
timestamp to generate an identifier for the created
hot backup. Subsequently, all other APIs operate on these identifiers.
The permissions required to use the /_admin/backup/* endpoints depends on the
setting of the --backup.options-api startup option.
Create a backup
POST
/_admin/backup/create
Creates a consistent local backup “as soon as possible”, very much
like a snapshot in time, with a given label. The ambiguity in the
phrase “as soon as possible” refers to the next window during which a
global write lock across all databases can be obtained in order to
guarantee consistency. Note that the backup at first resides on the
same machine and hard drive as the original data. Make sure to upload
it to a remote site for an actual backup.
Request Body application/json object
allowInconsistent
boolean
If this flag is set to true and no global transaction lock can be
acquired within the given timeout, a possibly inconsistent backup
is taken. The default for this flag is false and in this case
a timeout results in an HTTP 408 error.
force
boolean
If this flag is set to true and no global transaction lock can be acquired
within the given timeout, all running transactions are forcefully aborted to
ensure that a consistent backup can be created. This does not include
JavaScript transactions. It waits for the transactions to be aborted at most
timeout seconds. Thus using force the request timeout is doubled.
To abort transactions is almost certainly not what you want for your application.
In the presence of intermediate commits it can even destroy the atomicity of your
transactions. Use at your own risk, and only if you need a consistent backup at
all costs. The default and recommended value is false. If both
allowInconsistent and force are set to true, then the latter takes
precedence and transactions are aborted. This is only available in the cluster.
label
string
The label for this backup. The label is used together with a
timestamp string create a unique backup identifier, <timestamp>_<label>.
If no label is specified, the empty string is assumed and a default
UUID is created for this part of the ID.
timeout
number
The time in seconds that the operation tries to get a consistent
snapshot. The default is 120 seconds.
Responses
201
Created
If all is well, code 201 is returned.
400
Bad Request
If the create command is invoked with bad parameters or any HTTP
method other than POST, then an HTTP 400 is returned. The specifics
are detailed in the returned error document.
408
Request Timeout
If the operation cannot obtain a global transaction lock
within the timeout, then an HTTP 408 is returned.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/create' <<'EOF'
{
"label": "foo"
}
EOF
Show outputHTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 186
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 201,
"result" : {
"id" : "2024-11-06T11.55.43Z_foo",
"potentiallyInconsistent" : false,
"sizeInBytes" : 7966372,
"datetime" : "2024-11-06T11:55:43Z",
"nrDBServers" : 1,
"nrFiles" : 28
}
}
Restore a backup
POST
/_admin/backup/restore
Restores a consistent local backup from a
snapshot in time, with a given id. The backup snapshot must reside on
the ArangoDB service locally.
Request Body application/json object
id*
string
The id of the backup to restore from.
Responses
200
OK
Is returned if the backup could be restored. Note that there is an
inevitable discrepancy between the single server and the cluster. In a
single server, the request returns successfully, but the restore is
only executed afterwards. In the cluster, the request only returns when
the restore operation has been completed successfully. The cluster
behaviour is obviously the desired one, but in a single instance, one
cannot keep a connection open across a restart.
400
Bad Request
If the restore command is invoked with bad parameters or any HTTP
method other than POST, then an HTTP 400 is returned. The specifics
are detailed in the returned error document.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/restore' <<'EOF'
{
"id": "2024-11-06T11.55.43Z_7e669f1d-afa8-485f-8554-190c847bea32"
}
EOF
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 97
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : {
"previous" : "/var/lib/arangodb3/backups/DIRECTORY_TO_DELETE"
}
}
Delete a backup
POST
/_admin/backup/delete
Delete a specific local backup identified by the given id.
Request Body application/json object
id*
string
The identifier for this backup.
Responses
200
OK
If all is well, this code 200 is returned.
400
Bad Request
If the delete command is invoked with bad parameters or any HTTP
method other than POST, then an HTTP 400 is returned.
404
Not Found
If a backup corresponding to the identifier id cannot be found.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/delete' <<'EOF'
{
"id": "2024-11-06T11.55.46Z_8cc65ed5-a51e-435e-bf1f-46a9e471cc75"
}
EOF
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 38
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : {
}
}
List all backups
POST
/_admin/backup/list
Lists all locally found backups.
Request Body application/json object
id
string
The body can either be empty (in which case all available backups are
listed), or it can be an object with an attribute id, which
is a string. In the latter case the returned list
is restricted to the backup with the given id.
Responses
200
OK
If all is well, code 200 is returned.
400
Bad Request
If the list command is invoked with bad parameters, then an HTTP 400
is returned.
404
Not Found
If an id or a list of ids was given and the given ids were not found
as identifiers of a backup, an HTTP 404 Not Found is returned.
405
Method Not Allowed
If the list command is invoked with any HTTP
method other than POST, then an HTTP 405 Method Not Allowed is returned.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/list' <<'EOF'
{}
EOF
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1397
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : {
"server" : "SNGL-21b960e0-6c54-4409-ad64-61f4c5de3033",
"list" : {
"2024-11-06T11.55.46Z_8687a850-3adc-486b-bbaf-9f3110635880" : {
"id" : "2024-11-06T11.55.46Z_8687a850-3adc-486b-bbaf-9f3110635880",
"version" : "3.11.12",
"datetime" : "2024-11-06T11:55:46Z",
"keys" : [ ],
"sizeInBytes" : 7963238,
"nrFiles" : 29,
"nrDBServers" : 1,
"available" : true,
"nrPiecesPresent" : 1,
"potentiallyInconsistent" : false,
"countIncludesFilesOnly" : true
},
"2024-11-06T11.55.46Z_a85d99c8-6f22-404d-a074-9fdecbd910ec" : {
"id" : "2024-11-06T11.55.46Z_a85d99c8-6f22-404d-a074-9fdecbd910ec",
"version" : "3.11.12",
"datetime" : "2024-11-06T11:55:46Z",
"keys" : [ ],
"sizeInBytes" : 7963143,
"nrFiles" : 28,
"nrDBServers" : 1,
"available" : true,
"nrPiecesPresent" : 1,
"potentiallyInconsistent" : false,
"countIncludesFilesOnly" : true
},
"2024-11-06T11.55.43Z_7e669f1d-afa8-485f-8554-190c847bea32" : {
"id" : "2024-11-06T11.55.43Z_7e669f1d-afa8-485f-8554-190c847bea32",
"version" : "3.11.12",
"datetime" : "2024-11-06T11:55:43Z",
"keys" : [ ],
"sizeInBytes" : 7986548,
"nrFiles" : 31,
"nrDBServers" : 1,
"available" : true,
"nrPiecesPresent" : 1,
"potentiallyInconsistent" : false,
"countIncludesFilesOnly" : true
},
"2024-11-06T11.55.43Z_foo" : {
"id" : "2024-11-06T11.55.43Z_foo",
"version" : "3.11.12",
"datetime" : "2024-11-06T11:55:43Z",
"keys" : [ ],
"sizeInBytes" : 7966372,
"nrFiles" : 28,
"nrDBServers" : 1,
"available" : true,
"nrPiecesPresent" : 1,
"potentiallyInconsistent" : false,
"countIncludesFilesOnly" : true
}
}
}
}
Upload a backup to a remote repository
POST
/_admin/backup/upload
Upload a specific local backup to a remote repository, or query
progress on a previously scheduled upload operation, or abort
a running upload operation.
Request Body application/json object
abort
boolean
Set this to true if a running upload operation should be aborted. In
this case, the only other body parameter which is needed is uploadId.
config
object
Configuration of remote repository. This is required when an upload
operation is scheduled. In this case leave out the uploadId
attribute. See the description of the arangobackup program in the manual
for a description of the config object.
id
string
The identifier for this backup. This is required when an upload
operation is scheduled. In this case leave out the uploadId
attribute.
remoteRepository
string
URL of remote repository. This is required when an upload operation is
scheduled. In this case leave out the uploadId attribute. Provided repository
URLs are normalized and validated as follows: One single colon must appear
separating the configuration section name and the path. The URL prefix up to
the colon must exist as a key in the config object below. No slashes must
appear before the colon. Multiple back to back slashes are collapsed to one, as
.. and . are applied accordingly. Local repositories must be absolute
paths and must begin with a /. Trailing / are removed.
uploadId
string
Upload ID to specify for which upload operation progress is queried or
the upload operation to abort.
If you specify this, leave out all the above body parameters.
Responses
200
OK
If all is well, code 200 is returned if progress is inquired or the
operation is aborted.
202
Accepted
If all is well, code 202 is returned if a new operation is scheduled.
400
Bad Request
If the upload command is invoked with bad parameters or any HTTP
method other than POST, then an HTTP 400 is returned.
401
Unauthorized
If the authentication to the remote repository fails, then an HTTP
400 is returned.
404
Not Found
If a backup corresponding to the identifier id cannot be found, or if
there is no known upload operation with the given uploadId.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/upload' <<'EOF'
{
"id": "2024-11-06T11.55.46Z_c76dcb98-8aae-4ba5-9036-39c9e8f8e029",
"remoteRepository": "local://tmp/backups",
"config": {
"local": {
"type": "local"
}
}
}
EOF
Show outputHTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 56
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 202,
"result" : {
"uploadId" : "68374"
}
}
The result object of the body holds the uploadId string attribute which can
be used to follow the upload process.
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/upload' <<'EOF'
{
"uploadId": "68375"
}
EOF
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 222
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : {
"Timestamp" : "2024-11-06T11:55:46Z",
"UploadId" : "68375",
"Cancelled" : false,
"BackupId" : "2024-11-06T11.55.46Z_add1f013-ef9f-4dc7-8879-be73c5d0467d",
"DBServers" : {
"SNGL" : {
"Status" : "STARTED"
}
}
}
}
Download a backup from a remote repository
POST
/_admin/backup/download
Download a specific local backup from a remote repository, or query
progress on a previously scheduled download operation, or abort
a running download operation.
Request Body application/json object
abort
boolean
Set this to true if a running download operation should be aborted. In
this case, the only other body parameter which is needed is downloadId.
config*
object
Configuration of remote repository. This is required when a download
operation is scheduled. In this case leave out the downloadId
attribute. See the description of the arangobackup program in the manual
for a description of the config object.
downloadId
string
Download ID to specify for which download operation progress is queried, or
the download operation to abort.
If you specify this, leave out all the above body parameters.
id
string
The identifier for this backup. This is required when a download
operation is scheduled. In this case leave out the downloadId
attribute.
remoteRepository*
string
URL of remote repository. This is required when a download operation is
scheduled. In this case leave out the downloadId attribute. Provided
repository URLs are normalized and validated as follows: One single colon must
appear separating the configuration section name and the path. The URL prefix
up to the colon must exist as a key in the config object below. No slashes must
appear before the colon. Multiple back to back slashes are collapsed to one, as
.. and . are applied accordingly. Local repositories must be absolute paths
and must begin with a /. Trailing / are removed.
Responses
200
OK
If all is well, code 200 is returned if progress is inquired or the
operation is aborted.
202
Accepted
If all is well, code 202 is returned if a new operation is scheduled.
400
Bad Request
If the download command is invoked with bad parameters or any HTTP
method other than POST, then an HTTP 400 is returned.
401
Unauthorized
If the authentication to the remote repository fails, then an HTTP
401 is returned.
404
Not Found
If a backup corresponding to the identifier id cannot be found, or if
there is no known download operation with the given downloadId.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/download' <<'EOF'
{
"id": "2024-11-06T11.55.46Z_d82034df-44be-4aca-a65e-31dca5eca6f4",
"remoteRepository": "local://tmp/backups",
"config": {
"local": {
"type": "local"
}
}
}
EOF
Show outputHTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 58
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 202,
"result" : {
"downloadId" : "68381"
}
}
The result object of the body holds the downloadId string attribute which
can be used to follow the download process.
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_admin/backup/download' <<'EOF'
{
"downloadId": "68391"
}
EOF
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 224
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : {
"Timestamp" : "2024-11-06T11:56:16Z",
"DownloadId" : "68391",
"Cancelled" : false,
"BackupId" : "2024-11-06T11.56.01Z_b8f0cf56-555e-4612-b7c7-ce23408969ea",
"DBServers" : {
"SNGL" : {
"Status" : "STARTED"
}
}
}
}
