Document fields and parameters added to support cloud backup #2506
Conversation
|
Warning Rate limit exceeded@mdegat01 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 10 minutes and 34 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe pull request introduces enhancements to the Supervisor API documentation, focusing on backup-related endpoints and models. The changes expand the backup information by adding new fields like Changes
Sequence DiagramsequenceDiagram
participant Client
participant SupervisorAPI
participant BackupSystem
Client->>SupervisorAPI: Request Backup Creation
alt Full Backup
Client->>SupervisorAPI: POST /backups/new/full
else Partial Backup
Client->>SupervisorAPI: POST /backups/new/partial
end
SupervisorAPI->>BackupSystem: Initiate Backup
BackupSystem-->>SupervisorAPI: Generate Backup
SupervisorAPI-->>Client: Return Backup Details (size, locations)
This sequence diagram illustrates the high-level flow of backup creation through the Supervisor API, showing how a client can request either a full or partial backup, and receive detailed information about the created backup. Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
mdegat01
force-pushed
the
cloud-backup-support
branch
from
d7b7bd4 to
d905151
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/api/supervisor/endpoints.md (1)
934-944: Consider clarifying the 'ALL' behavior for addons.While the documentation correctly shows that
addonscan acceptALL, it would be helpful to explicitly state that this includes all currently installed add-ons.-| 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 | +| addons | list or `ALL` | Content | A list of strings representing add-on slugs. Provide the string `ALL` instead of a list to automatically include all add-ons that are currently installed in the system |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/api/supervisor/endpoints.md(9 hunks)docs/api/supervisor/models.md(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/api/supervisor/endpoints.md
892-892: Emphasis used instead of a heading
null
(MD036, no-emphasis-as-heading)
899-899: Emphasis used instead of a heading
null
(MD036, no-emphasis-as-heading)
1013-1013: Emphasis used instead of a heading
null
(MD036, no-emphasis-as-heading)
1019-1019: Emphasis used instead of a heading
null
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
🔇 Additional comments (7)
docs/api/supervisor/models.md (4)
171-185: Well-documented backup model changes!The changes clearly document the new cloud backup capabilities while properly marking deprecated fields. The new
location_attributesfield provides a flexible way to track backup metadata across multiple locations.
186-191: Clear and consistent location attributes documentation!The location attributes structure is well-defined and aligns perfectly with its usage in the Backup model.
205-224: Comprehensive backup details model documentation!The changes thoroughly document:
- New fields for cloud backup support
- Version tracking capabilities
- Optional Home Assistant inclusion
- Consistent deprecation notices
292-305: Helpful mount model enhancements!The changes improve the documentation by:
- Clarifying which fields are available in requests vs responses
- Adding support for read-only mounts
- Including user-facing path information
docs/api/supervisor/endpoints.md (3)
784-793: Clear and consistent backup response example!The example accurately demonstrates the structure of the new backup fields, aligning perfectly with the model documentation.
892-905: Excellent query parameter documentation!The documentation clearly explains:
- Available query parameters
- Multiple location support
- Common usage examples
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
892-892: Emphasis used instead of a heading
null(MD036, no-emphasis-as-heading)
899-899: Emphasis used instead of a heading
null(MD036, no-emphasis-as-heading)
879-885: Valuable error handling documentation!The note provides important guidance for API consumers about:
- Additional job_id field in error responses
- How to handle complex error scenarios
- Where to find detailed error information
| | compressed | boolean | True | `false` to create uncompressed backups | | ||
| | location | string or null | True | Name of a backup mount or `null` for /backup | | ||
| | location | list or string | True | Name of a backup mount or `.local` for /backup. Use a list to the make backup in multiple places | |
There was a problem hiding this comment.
| | location | list or string | True | Name of a backup mount or `.local` for /backup. Use a list to the make backup in multiple places | | |
| | location | list or string | True | Name of a backup mount or `.local` for /backup. Use a list to the store the backup in multiple places | |
| | 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 | |
There was a problem hiding this comment.
I'd mark the fields we don't have in the client library as deprecated here too (related to home-assistant-libs/python-supervisor-client#47
| | 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 | | |
| | size | float | yes | Size of the backup in MB (rounded) (deprecated) | | |
| | size_bytes | int | yes | Size of the backup in bytes (deprecated) | | |
| | 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 (deprecated) | | |
| | protected | boolean | yes | `true` if the backup is password protected | |
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Proposed change
Document the fields and parameters added to Supervisor's API in support of the cloud backup work. Additionally fixes some small gaps in the backup response model documentation I noticed.
This is catch-up after a number of PRs to Supervisor. I'm actually going to link the Supervisor client library PRs rather then Supervisor ones as they are easier to review since they match the API changes and almost nothing else. Whereas the Supervisor PRs include a lot more then the API changes. They also link back to the corresponding Supervisor PRs for reviewing there as well:
Type of change
Additional information
Summary by CodeRabbit
Summary by CodeRabbit
BackupandBackup details, improving data representation.