lee/backrest
1
0
Fork 0
mirror of https://github.com/garethgeorge/backrest.git synced 2026-09-20 23:15:44 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

chore: doc updates

Browse Source
This commit is contained in:
Gareth George
2025-01-23 20:40:03 -08:00
parent e2402e2748
commit 09449a814a
2 changed files with 40 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/2.docs/3.api.md
+38
View File
@@ -0,0 +1,38 @@
# API
Backrest provides a limited HTTP API for interacting with the backrest service. To use the API authentication must be disabled (or you can optionally provide a username and password with basic auth headers) e.g. `curl -u user:password http://localhost:9898/v1/<endpoint>`
All of Backrest's API endpoints are defined as a gRPC service and are exposed over HTTP by a JSON RPC gateway for easy scripting. For the full service definition see [service.proto](https://github.com/garethgeorge/backrest/blob/main/proto/v1/service.proto).
::alert{type="warning"}
Only the APIs documented below are considered stable, other endpoints may be subject to change.
::
### Backup API
The backup API can be used to trigger execution of a plan e.g.
```
curl -X POST 'localhost:9898/v1.Backrest/Backup' --data '{"value": "YOUR_PLAN_ID"}' -H 'Content-Type: application/json'
```
The request will block until the operation has completed. A 200 response means the backup completed successfully, if the request times out the operation will continue in the background.
### Operations API
The operations API can be used to fetch operation history e.g.
```
curl -X POST 'localhost:9898/v1.Backrest/GetOperations' --data '{}' -H 'Content-Type: application/json'
```
More complex selectors can be applied e.g.
```
curl -X POST 'localhost:9898/v1.Backrest/GetOperations' --data '{"selector": {"planId": "YOUR_PLAN_ID"}}' -H 'Content-Type: application/json'
```
For details on the structure of operations returned see the [operations.proto](https://github.com/garethgeorge/backrest/blob/main/proto/v1/operations.proto).
::alert{type="warning"}
The structure of the operation history is subject to change over time. Different fields may be added or removed in future versions.
::
docs/content/3.cookbooks/1.command-hook-examples.md
+2 -8
View File
@@ -14,7 +14,6 @@ When run on `CONDITION_SNAPSHOT_START` command hooks have the ability to send co
## Examples
#### Notify a healthcheck service
Ping a healthcheck service (e.g. https://healthchecks.io/ in the example) to notify it of backup status (or failure) using a command hook.
@@ -146,7 +145,8 @@ fi
**Error Behavior:** `ON_ERROR_CANCEL`
### Windows PowerShell examples
## Windows Notification Examples
#### GUI message box on error condition
The message box stays on screen until acknowledged by the user. Use the same script for both backup plan and repo settings to catch errors.
@@ -163,8 +163,6 @@ $icon = [System.Windows.Forms.MessageBoxIcon]::Error
$title = "Backrest"
$message = '{{ .Summary }}'
[System.Windows.Forms.MessageBox]::Show($message, $title, $buttons, $icon, $defbutton, $options)
# Include this comment and the line above it. See https://github.com/garethgeorge/backrest/issues/400
```
#### GUI toast warning notification
Toast or app notifications appear for a short time before disappearing without user acknowledgement.
@@ -185,8 +183,6 @@ Start-Sleep -Seconds(5)
$balloon.Visible = $false
$balloon.Icon.Dispose()
$balloon.Dispose()
# Include this comment and the line above it. See https://github.com/garethgeorge/backrest/issues/400
```
#### GUI toast information notification
@@ -206,6 +202,4 @@ Start-Sleep -Seconds(5)
$balloon.Visible = $false
$balloon.Icon.Dispose()
$balloon.Dispose()
# Include this comment and the line above it. See https://github.com/garethgeorge/backrest/issues/400
```