From 4b03a7028f4f1a8ea07308485544d010e422b98e Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 14:08:40 -0700 Subject: vyos-api: T9087: T9092: apply review feedback (line length, retry safety) Convert the multi-field-node table to wrapped list items per the 80-char docs guideline, and rework the bulk-apply bullet to reconcile state before retrying after a timeout instead of recommending blind retries. Co-Authored-By: Claude Fable 5 (cherry picked from commit 2510eefadc8e7520e7f85f45a2b29fdab634474a) --- docs/automation/vyos-api.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md index 8007a75b..627a7901 100644 --- a/docs/automation/vyos-api.md +++ b/docs/automation/vyos-api.md @@ -486,11 +486,12 @@ configuration node cannot be staged across separate requests: everything the commit validators require must arrive in the same request, passed as a list of operations (see below). Common examples: -| Node | Must be set in the same request | -|------|---------------------------------| -| `system task-scheduler task ` | `executable` together with `interval` (or `crontab-spec`) | -| `nat destination rule ` | `translation` together with the other rule fields | -| `firewall ... rule ` | `action` in the request that creates the rule; `protocol` together with `port` or `port-group` | +- `system task-scheduler task `: `executable` together with + `interval` (or `crontab-spec`). +- `nat destination rule `: `translation` together with the other rule + fields. +- `firewall ... rule `: `action` in the request that creates the rule; + `protocol` together with `port` or `port-group`. Sending such fields in separate requests fails validation with errors such as `Protocol must be defined if specifying a port or port-group` or @@ -618,9 +619,11 @@ Large applies over the API (initial provisioning, firewall migrations with hundreds of operations) benefit from a few precautions: - Prefer several requests of moderate size over one very large list of - operations, and retry per operation on failure. A very large single - commit can run longer than the HTTP gateway allows and return a timeout - even though the commit itself eventually succeeds. + operations. A very large single commit can run longer than the HTTP + gateway allows and return a timeout even though the commit itself + eventually succeeds — after a timeout, reconcile the configuration + state (for example with `/retrieve`) before retrying, so an + already-applied change is not replayed. - Commits that reference `geoip` country codes or `remote-group` URLs are significantly more expensive than plain set operations, because they trigger database or remote-list processing. Apply those one per request. -- cgit v1.2.3