From d905151a961d0a55f5faec30584f61e6baf47a4d Mon Sep 17 00:00:00 2001 From: Mike Degatano Date: Thu, 30 Jan 2025 15:48:46 -0500 Subject: [PATCH] Document fields added and changed from continued cloud backup effort --- docs/api/supervisor/endpoints.md | 66 ++++++++++++++++++----------- docs/api/supervisor/models.md | 73 ++++++++++++++++++-------------- 2 files changed, 82 insertions(+), 57 deletions(-) diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md index 2374b8eb..1b77cc5d 100644 --- a/docs/api/supervisor/endpoints.md +++ b/docs/api/supervisor/endpoints.md @@ -785,6 +785,12 @@ Return a list of [Backups](api/supervisor/models.md#backup) "protected": true, "location": "MountedBackups", "locations": ["MountedBackups"], + "location_attributes": { + "MountedBackups": { + "protected": true, + "size_bytes": 44070259 + } + }, "compressed": true, "content": { "homeassistant": true, @@ -825,6 +831,12 @@ Return information about backup manager. "compressed": true, "location": null, "locations": [null], + "location_attributes": { + ".local": { + "protected": true, + "size_bytes": 44070259 + } + }, "content": { "homeassistant": true, "addons": ["awesome_addon"], @@ -849,10 +861,11 @@ Create a full backup. | name | string | True | The name you want to give the backup | | password | string | True | The password you want to give the backup | | compressed | boolean | True | `false` to create uncompressed backups | -| location | list, string or null | True | Name of a backup mount or `null` for /backup. Use a list of backup mounts or `null` to make backup in multiple places | +| location | list or string | True | Name of a backup mount or `.local` for `/backup`. Use a list to make the backup in multiple places | | homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup | | background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. | | extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases | +| filename | string | True | The name for the backup file created | **Example response:** @@ -880,13 +893,15 @@ Upload a backup. | key | multiple | description | | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| location | Yes | The name of the backup mount to upload to. Use empty string for `/backup`. Provide multiple locations to upload to multiple places | +| location | Yes | The name of the backup mount to upload to. Use `.local` for `/backup`. Provide multiple locations to upload to multiple places | +| filename | No | The name for the backup file created | *Examples* -- `?location=` - Upload to `/backup` +- `?location=.local` - Upload to `/backup` - `?location=MountedBackups` - Upload to backup mount named `MountedBackup` -- `?location=&location=MountedBackups` - Upload to both of the above places +- `?location=.local&location=MountedBackups` - Upload to both of the above places +- `?filename=my_backup.tar` - Create backup file in default backup location with name `my_backup.tar` **Example response:** @@ -920,10 +935,11 @@ Create a partial backup. | addons | list or `ALL` | Content | A list of strings representing add-on slugs. Provide the string `ALL` instead of a list to include all currently installed add-ons | | folders | list | Content | A list of strings representing directories | | compressed | boolean | True | `false` to create uncompressed backups | -| location | list, string or null | True | Name of a backup mount or `null` for /backup. Use a list of backup mounts or `null` to make backup in multiple places | +| location | list or string | True | Name of a backup mount or `.local` for /backup. Use a list to the make backup in multiple places | | homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup | | background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. | | extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases | +| filename | string | True | The name for the backup file created | **You need to supply at least one key of the ones marked "Content" in the optional column in the payload.** @@ -996,13 +1012,13 @@ Download the backup file with the given slug. **Query** -| key | multiple | description | -| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| location | No | Specify which location to download the backup from of the ones it exists in. Use empty string for `/backup` (equivalent to `null` in the `locations` field of [Backup](api/supervisor/models.md#backup)) | +| key | multiple | description | +| --------- | -------- | ------------------------------------------------------------------------------------------------------- | +| location | No | Specify which location to download the backup from of the ones it exists in. Use `.local` for `/backup` | *Examples* -- `?location=` - Download from `/backup` +- `?location=.local` - Download from `/backup` - `?location=MountedBackups` - Download from backup mount named `MountedBackup` @@ -1019,9 +1035,9 @@ Removes the backup file with the given slug. **Payload:** -| key | type | optional | description | -| -------- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| location | list | True | Specify which locations to remove the backup from instead of removing it from all locations. See `locations` field of [Backup](api/supervisor/models.md#backup)| +| key | type | optional | description | +| -------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| location | list | True | Specify which locations to remove the backup from instead of removing it from all locations. See `location_attributes` field from `/backups//info` for locations | @@ -1031,11 +1047,11 @@ Does a full restore of the backup with the given slug. **Payload:** -| key | type | optional | description | -| ---------- | -------------- | -------- | ------------------------------------ | -| password | string | True | The password for the backup if any | -| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. | -| location | string or null | True | Specify which location to restore the backup from of the ones it exists in. See `locations` field of [Backup](api/supervisor/models.md#backup) | +| key | type | optional | description | +| ---------- | ------- | -------- | ------------------------------------ | +| password | string | True | The password for the backup if any | +| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. | +| location | string | True | Specify which location to restore the backup from of the ones it exists in. See `location_attributes` field from `/backups//info` for locations | **Example response:** @@ -1060,14 +1076,14 @@ Does a partial restore of the backup with the given slug. **Payload:** -| key | type | optional | description | -| ------------- | -------------- | -------- | ---------------------------------------------- | -| homeassistant | boolean | Content | `true` if Home Assistant should be restored | -| addons | list | Content | A list of add-on slugs that should be restored | -| folders | list | Content | A list of directories that should be restored | -| password | string | True | The password for the backup if any | -| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. | -| location | string or null | True | Specify which location to restore the backup from of the ones it exists in. See `locations` field of [Backup](api/supervisor/models.md#backup) | +| key | type | optional | description | +| ------------- | ------- | -------- | ---------------------------------------------- | +| homeassistant | boolean | Content | `true` if Home Assistant should be restored | +| addons | list | Content | A list of add-on slugs that should be restored | +| folders | list | Content | A list of directories that should be restored | +| password | string | True | The password for the backup if any | +| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. | +| location | string | True | Specify which location to restore the backup from of the ones it exists in. See `location_attributes` field from `/backups//info` for locations | **You need to supply at least one key of the ones marked "Content" in the optional column in the payload.** diff --git a/docs/api/supervisor/models.md b/docs/api/supervisor/models.md index 2497fcae..99cac35a 100644 --- a/docs/api/supervisor/models.md +++ b/docs/api/supervisor/models.md @@ -168,19 +168,27 @@ These models are describing objects that are getting returned from the superviso ## Backup -| key | type | description | -| ---------- | -------------- | -------------------------------------------------------------------------------------- | -| slug | string | A generated slug for the backup | -| date | string | ISO date string representation of the date the backup was created | -| name | string | The name given to the backup | -| type | string | The type of backup (full, partial) | -| size | float | Size of the backup in MB (rounded) | -| size_bytes | int | Size of the backup in bytes | -| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally | -| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally | -| protected | boolean | `true` if the backup is password protected | -| content | dictionary | A dictionary describing the content of the backup | -| compressed | boolean | `true` if the backup is saved in a compressed archive | +| key | type | deprecated | description | +| ---------- | -------------- | ---------- | -------------------------------------------------------------------------------------- | +| slug | string | no | A generated slug for the backup | +| date | string | no | ISO date string representation of the date the backup was created | +| name | string | no | The name given to the backup | +| type | string | no | The type of backup (full, partial) | +| content | dictionary | no | A dictionary describing the content of the backup | +| compressed | boolean | no | `true` if the backup is saved in a compressed archive | +| location_attributes | dictionary | no | A dictionary of [`location_attributes`](#backup---location-attributes) keyed by location the backup exists in. `.local` is the key if backup exists is in local `/backup` folder | +| size | float | yes | Size of the backup in MB (rounded) | +| size_bytes | int | yes | Size of the backup in bytes | +| location | string or null | yes | The name of the backup mount it's stored on. `null` if it's stored locally | +| locations | list | yes | List of names of all backup mounts it's stored on and/or `null` if it's stored locally | +| protected | boolean | yes | `true` if the backup is password protected | + +### Backup -> location attributes + +| key | type | description | +| ---------- | -------------- | ------------------------------------- | +| protected | boolean | Backup is password protected | +| size_bytes | int | Size of the backup in bytes | ### Backup -> content @@ -194,25 +202,26 @@ The `content` key of a backup object contains the following keys: ## Backup details -| key | type | description | -| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------- | -| slug | string | A generated slug for the backup | -| type | string | The type of backup (full, partial) | -| name | string | The name given to the backup | -| date | string | ISO date string representation of the date the backup was created | -| size | float | The size of the backup in MB (rounded) | -| size_bytes | int | Size of the backup in bytes | -| compressed | boolean | `true` if the backup is saved in a compressed archive | -| protected | boolean | `true` if the backup is password protected | -| supervisor_version | string | The version of Supervisor the backup was created on. Backup can only be restored on Supervisor with same version or later | -| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally. | -| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally | -| homeassistant | string or null | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup | -| addons | list | A list of add-ons in the backup. Add-ons are represented as a dictionary with these keys [`slug`,`name`,`version`,`size`] | -| repositories | list | A list of add-on repository URL's as strings | -| folders | list | A list of strings representing directories | -| homeassistant_exclude_database | boolean | `true` if the Home Assistant database file was excluded from this backup | -| extra | dictionary | A dictionary of extra metadata set by client on creation of the backup | +| key | type | deprecated | description | +| ------------------------------ | -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- | +| slug | string | no | A generated slug for the backup | +| type | string | no | The type of backup (full, partial) | +| name | string | no | The name given to the backup | +| date | string | no | ISO date string representation of the date the backup was created | +| compressed | boolean | no | `true` if the backup is saved in a compressed archive | +| location_attributes | dictionary | no | A dictionary of [`location_attributes`](#backup---location-attributes) keyed by location the backup exists in. `.local` is the key if backup exists is in local `/backup` folder | +| supervisor_version | string | no | The version of Supervisor the backup was created on. Backup can only be restored on Supervisor with same version or later | +| homeassistant | string or null | no | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup | +| addons | list | no | A list of add-ons in the backup. Add-ons are represented as a dictionary with these keys [`slug`,`name`,`version`,`size`] | +| repositories | list | no | A list of add-on repository URL's as strings | +| folders | list | no | A list of strings representing directories | +| homeassistant_exclude_database | boolean | no | `true` if the Home Assistant database file was excluded from this backup | +| extra | dictionary | no | A dictionary of extra metadata set by client on creation of the backup | +| size | float | yes | Size of the backup in MB (rounded) | +| size_bytes | int | yes | Size of the backup in bytes | +| location | string or null | yes | The name of the backup mount it's stored on. `null` if it's stored locally | +| locations | list | yes | List of names of all backup mounts it's stored on and/or `null` if it's stored locally | +| protected | boolean | yes | `true` if the backup is password protected | ## Stats