From 6b4e9015744ab8c9f17a6b8e23387cd676b1d827 Mon Sep 17 00:00:00 2001 From: roberto berto Date: Sun, 2 Nov 2025 22:54:44 +0000 Subject: feat: v0.4.0 - Architecture refactor, bug fixes, and quality improvements - Fixed #25: config_file_save/load now include path: [] in payload - Added exception hierarchy (SDKError, HttpError, ApiError, ValidationError) - Added utility functions (json, ids, paths) - Added structured logging with request ID tracking - Added optional Pydantic validation models - Refactored to pyvyos.core.* structure with backward compatibility shims - Moved JSON specs to docs/development/vyos_api/ - Added comprehensive test suite (19 shim tests, 16 utils tests, 6 exception tests) - Updated pyproject.toml for uv sync editable installation - Added development documentation (architecture, roadmap, quality guidelines) Maintains 100% backward compatibility with 0.3.0 --- docs/development/architecture.md | 77 ++++++++++++++++++++++ docs/development/quality-and-utils.md | 72 ++++++++++++++++++++ docs/development/refactor-roadmap.md | 56 ++++++++++++++++ docs/development/vyos_api/config-file-load.json | 2 + docs/development/vyos_api/config-file-save.json | 58 ++++++++++++++++ docs/development/vyos_api/configure-delete.json | 2 + .../vyos_api/configure-multiple-op.json | 2 + docs/development/vyos_api/configure-set.json | 2 + docs/development/vyos_api/generate.json | 2 + docs/development/vyos_api/image-add.json | 2 + docs/development/vyos_api/image-delete.json | 2 + docs/development/vyos_api/index.json | 2 + docs/development/vyos_api/poweroff.json | 2 + docs/development/vyos_api/reboot.json | 2 + docs/development/vyos_api/reset.json | 2 + .../vyos_api/retrieve-return-values.json | 2 + .../development/vyos_api/retrieve-show-config.json | 2 + docs/development/vyos_api/schema.json | 2 + docs/development/vyos_api/show.json | 2 + 19 files changed, 293 insertions(+) create mode 100644 docs/development/architecture.md create mode 100644 docs/development/quality-and-utils.md create mode 100644 docs/development/refactor-roadmap.md create mode 100644 docs/development/vyos_api/config-file-load.json create mode 100644 docs/development/vyos_api/config-file-save.json create mode 100644 docs/development/vyos_api/configure-delete.json create mode 100644 docs/development/vyos_api/configure-multiple-op.json create mode 100644 docs/development/vyos_api/configure-set.json create mode 100644 docs/development/vyos_api/generate.json create mode 100644 docs/development/vyos_api/image-add.json create mode 100644 docs/development/vyos_api/image-delete.json create mode 100644 docs/development/vyos_api/index.json create mode 100644 docs/development/vyos_api/poweroff.json create mode 100644 docs/development/vyos_api/reboot.json create mode 100644 docs/development/vyos_api/reset.json create mode 100644 docs/development/vyos_api/retrieve-return-values.json create mode 100644 docs/development/vyos_api/retrieve-show-config.json create mode 100644 docs/development/vyos_api/schema.json create mode 100644 docs/development/vyos_api/show.json (limited to 'docs/development') diff --git a/docs/development/architecture.md b/docs/development/architecture.md new file mode 100644 index 0000000..aceda08 --- /dev/null +++ b/docs/development/architecture.md @@ -0,0 +1,77 @@ +# Development Architecture (Proposed) + +## Goals +- Strong separation of concerns (transport, domain, specs, utils) +- Backward compatibility for 0.3.0 via shims +- Clear public API surface and internal boundaries +- Minimal maintenance burden for a public, official SDK + +## Source Layout (file tree) +``` +pyvyos/ + __init__.py # public API exports (VyDevice, ApiResponse) + core/ # internal, stable layers + __init__.py + rest_client.py # RestClient, ApiResponse (transport layer) + device.py # VyDevice (domain layer) + specs/ # optional Pydantic models (validation) + __init__.py + models.py # base models (ApiRequest/Response) + commands/ # split by responsibility + __init__.py + configure.py # set, delete, multiple_op + retrieve.py # show_config, return_values + config_file.py # save, load (path: []) + show.py # show + generate.py # generate + reset.py # reset + system.py # reboot, poweroff + image.py # add, delete + utils/ # reusable helpers (no side effects) + __init__.py + json.py # safe_json, redact_key + http.py # timeouts, retries (future) + paths.py # path builder helpers + ids.py # request_id helpers + exceptions.py # typed exceptions (SDKError, HttpError, ApiError) + types.py # public typing aliases if needed + device.py # shim re-export (compat) + rest.py # shim re-export (compat) + vyos_api/ # JSON specs (docs/reference, optional at runtime) +``` + +## Layers & Responsibilities +- Transport (core.rest_client): HTTP, payload assembly, response validation +- Domain (core.device): high-level methods (configure, show, reset, etc.) +- Specs (specs.*): optional Pydantic models to validate requests/answers +- Utils: pure helpers (formatting, ids, path building) +- Shims (device.py, rest.py): ensure 0.3.0 compatibility + +## Public API Surface +- `from pyvyos import VyDevice, ApiResponse` +- Stable imports; internal moves hidden by shims + +## Compatibility Strategy +- Keep shims until 1.0.0 +- Deprecation policy: warn after N minors, remove at next major +- Document migration path (import from `pyvyos.core` for new code) + +## Data Validation Flow (optional) +- App builds `path` with utils.paths +- If validation enabled, use `specs.commands.*` models +- RestClient serializes payload and executes request +- Response validated (structure: success/data/error) + +## Testing Strategy +- Unit: core.rest_client and core.device isolated via monkeypatch +- Contract: JSON fixtures mirror VyOS responses +- E2E (future): optional with test VyOS VM + +## Packaging +- Include `vyos_api/` only if needed at runtime +- Otherwise treat it as docs/reference, not required by the package + +## Naming & Conventions +- Use underscores `_` in file and module names +- One responsibility per module (keep files small) +- Typed public APIs, specific exceptions, no prints (only logging) diff --git a/docs/development/quality-and-utils.md b/docs/development/quality-and-utils.md new file mode 100644 index 0000000..ff78ec2 --- /dev/null +++ b/docs/development/quality-and-utils.md @@ -0,0 +1,72 @@ +# Quality, Utils, and Pitfalls + +## Goals +- Reduce regressions and supportability burden +- Consistent error handling and logging +- Clear utilities to avoid duplication + +## Exceptions (typed) +- `SDKError` (base) +- `HttpError(status, message)` +- `ApiError(message, details=None)` # when success=False +- `ValidationError(message)` # client-side validation + +## Logging +- Use `logging.getLogger("pyvyos")` +- Include: op, command, status, elapsed_ms, request_id +- Redact secrets (api key) – via `utils.json.redact_key(data, keys=["key"])` +- Default INFO; DEBUG guarded by env `PYVYOS_DEBUG=1` + +## Timeouts & Retries +- Default timeout: 10s (configurable) +- No implicit retries by default +- Future: retry idempotent ops only (exponential backoff) + +## Security +- `verify=True` by default +- Document `urllib3.disable_warnings()` only for dev +- Never log secrets or full payloads by default + +## Utilities (proposal) +- `utils.paths.build(*segments) -> list[str]` +- `utils.ids.request_id() -> str` +- `utils.json.safe_dumps(obj) -> str` (with redaction) +- `utils.http.timeout(seconds) -> int` (normalize) + +## Validation (optional) +- `specs.commands.*` Pydantic models validate request structures +- Enforce path rules (e.g., config-file requires `path=[]`) +- Gate behind feature flag or optional dependency group + +## Testing +- Unit: small, isolated, no real I/O +- Contract: success/error fixtures per command +- Naming: `test_should__when_` +- Use monkeypatch on `_execute_request` + +## Documentation +- Keep developer docs scoped and short (≤100 lines) +- Update api-reference and path rules on changes + +## Style & Types +- Type hints on public APIs, avoid `Any` +- Early returns, no deep nesting, no bare `except` +- Constants for command/operation strings + +## Release Hygiene +- Conventional commits; CHANGELOG generated +- Tag every release; ensure `git push --tags` +- Patch bumps for fixes, minor for features + +## Potential Pitfalls & Fixes +- Path handling inconsistencies → centralize in RestClient +- Logging secrets → redact before logging +- Tight coupling device↔transport → maintain clean core boundaries +- Hidden breaking changes → keep shims until 1.0.0 +- Non-deterministic tests → remove sleeps, use fixed seeds + +## Next Steps (ordered) +1. Introduce `exceptions.py` and wire into RestClient +2. Add `utils/` with `json.py`, `paths.py`, `ids.py` +3. Add optional `specs/` models for high-value commands +4. CI: lint+type-check, codecov, test matrix diff --git a/docs/development/refactor-roadmap.md b/docs/development/refactor-roadmap.md new file mode 100644 index 0000000..eeee879 --- /dev/null +++ b/docs/development/refactor-roadmap.md @@ -0,0 +1,56 @@ +# Refactor Roadmap (Prioritized) + +## Priorities +- P0 (now): safety, compatibility, correctness +- P1 (next): validation, observability, developer UX +- P2 (later): performance, async, resiliency + +## P0 — Immediate +- Stabilize transport: keep `_get_payload(include_empty_path)`; special-case `config-file` +- Keep shims: `pyvyos/device.py` and `pyvyos/rest.py` re-export from `pyvyos/core/*` +- Typed exceptions: introduce `SDKError`, `HttpError`, `ApiError`, `ValidationError` +- Timeouts: ensure sane defaults, expose in `VyDevice` +- Logging: centralize in transport, structured key fields (op, command, status) +- Tests: payload assertions for `config-file` (path: []), regression for others +- Docs: architecture and path rules (done) + +## P1 — Short Term +- Specs (optional): Pydantic models in `pyvyos/specs/commands/*` +- `utils/`: path builders, request_id, safe_json redaction +- Deprecation policy: note in README; warn on internal imports (future only) +- CI: test matrix (Python 3.13), codecov, lint (ruff/flake8), type-check (pyright/mypy) +- Release: conventional commits + CHANGELOG; ensure tags push +- Docs: contributor guide, release playbook (short) + +## P2 — Medium Term +- Async client: `AsyncRestClient` (aiohttp/httpx), opt-in +- Retries & backoff: idempotent ops only; circuit-breaker (future) +- Rate limiting: client-side token bucket (opt-in) +- Caching: read-only `show/retrieve` (TTL) optional +- Batch ops: smarter `configure_multiple_op` planning + +## Migration & Compatibility +- Public API: `from pyvyos import VyDevice, ApiResponse` (stable) +- Internal: prefer `pyvyos.core.*` for new code +- Shims stay until 1.0.0; removal at next major only + +## Testing Plan +- Unit: transport (errors, timeouts), domain (paths) +- Contract: sample JSON fixtures per command +- E2E: optional job against a test VyOS (gated, non-blocking) + +## Release Flow (lean) +- Branch: feature → PR → squash merge +- Pre-release (optional): `-rcX` tags +- Tag + publish: GitHub Action (uv build + PyPI publish) + +## Risks & Mitigations +- Hidden breakages → keep shims, add regression tests +- API drift (VyOS) → specs folder eases updates +- Logging noise → default INFO; debug gated via env +- Security → default `verify=True`, redact secrets in logs + +## Success Criteria +- 0.3.x users unaffected +- New structure adopted by contributors +- Lower maintenance overhead (fewer regressions) diff --git a/docs/development/vyos_api/config-file-load.json b/docs/development/vyos_api/config-file-load.json new file mode 100644 index 0000000..3e1fcef --- /dev/null +++ b/docs/development/vyos_api/config-file-load.json @@ -0,0 +1,2 @@ +{"command":"config-file","operation":"load","description":"Load configuration from a file.","endpoint":"/config-file","method":"POST","request":{"payload":{"data":{"op":"load","path":[],"file":"/config/backup.config"},"key":"your-api-key"},"example":{"op":"load","path":[],"file":"/config/backup.config"}},"response":{"success":{"success":true,"data":null,"error":null},"error":{"success":false,"data":null,"error":"Failed to load configuration file"}},"parameters":{"file":{"type":"string","required":true,"description":"Path to the configuration file to load","example":"/config/backup.config"},"path":{"type":"array","required":false,"description":"Path parameter (required by API, typically empty array)","default":[],"example":[]}},"python_usage":"device.config_file_load(file=\"/config/backup.config\")","notes":"The path parameter is required by the VyOS API even though it's typically empty for load operations."} + diff --git a/docs/development/vyos_api/config-file-save.json b/docs/development/vyos_api/config-file-save.json new file mode 100644 index 0000000..563e0ad --- /dev/null +++ b/docs/development/vyos_api/config-file-save.json @@ -0,0 +1,58 @@ +{ + "command": "config-file", + "operation": "save", + "description": "Save the current configuration to a file.", + "endpoint": "/config-file", + "method": "POST", + "request": { + "payload": { + "data": { + "op": "save", + "path": [], + "file": "/config/backup.config" + }, + "key": "your-api-key" + }, + "example": { + "with_file": { + "op": "save", + "path": [], + "file": "/config/backup.config" + }, + "default_location": { + "op": "save", + "path": [] + } + } + }, + "response": { + "success": { + "success": true, + "data": "", + "error": null + }, + "error": { + "success": false, + "data": null, + "error": "Failed to save configuration" + } + }, + "parameters": { + "file": { + "type": "string", + "required": false, + "description": "Path to the file where configuration will be saved. If not provided, uses default location.", + "example": "/config/backup.config" + }, + "path": { + "type": "array", + "required": false, + "description": "Path parameter (required by API, typically empty array)", + "default": [], + "example": [] + } + }, + "python_usage": "device.config_file_save(file=\"/config/backup.config\")", + "notes": "The path parameter is required by the VyOS API even though it's typically empty for save operations." +} + diff --git a/docs/development/vyos_api/configure-delete.json b/docs/development/vyos_api/configure-delete.json new file mode 100644 index 0000000..f68c5c8 --- /dev/null +++ b/docs/development/vyos_api/configure-delete.json @@ -0,0 +1,2 @@ +{"command":"configure","operation":"delete","description":"Delete configuration values based on a path.","endpoint":"/configure","method":"POST","request":{"payload":{"data":{"op":"delete","path":["interfaces","dummy","dum1"]},"key":"your-api-key"},"example":{"op":"delete","path":["interfaces","dummy","dum1"]}},"response":{"success":{"success":true,"data":{},"error":null},"error":{"success":false,"data":null,"error":"Path does not exist"}},"parameters":{"path":{"type":"array","required":true,"description":"Configuration path to delete as array of strings","example":["interfaces","dummy","dum1"]}},"python_usage":"device.configure_delete(path=[\"interfaces\", \"dummy\", \"dum1\"])"} + diff --git a/docs/development/vyos_api/configure-multiple-op.json b/docs/development/vyos_api/configure-multiple-op.json new file mode 100644 index 0000000..a0d0ab4 --- /dev/null +++ b/docs/development/vyos_api/configure-multiple-op.json @@ -0,0 +1,2 @@ +{"command":"configure","operation":"multiple","description":"Execute multiple configuration operations atomically in a single request.","endpoint":"/configure","method":"POST","request":{"payload":{"data":[{"op":"set","path":["interfaces","dummy","dum1","address","192.168.1.1/24"]},{"op":"delete","path":["interfaces","dummy","old1"]}],"key":"your-api-key"},"example":[{"op":"set","path":["interfaces","dummy","dum1","address","192.168.1.1/24"]},{"op":"set","path":["interfaces","dummy","dum1","description","Test interface"]},{"op":"delete","path":["interfaces","dummy","old1"]}]},"response":{"success":{"success":true,"data":null,"error":null},"error":{"success":false,"data":null,"error":"One or more operations failed"}},"parameters":{"op_path":{"type":"array","required":true,"description":"Array of operation objects, each with 'op' and 'path'","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["set","delete"]},"path":{"type":"array","items":{"type":"string"}}}},"example":[{"op":"set","path":["interfaces","dummy","dum1","address","192.168.1.1/24"]},{"op":"delete","path":["interfaces","dummy","old1"]}]}},"python_usage":"device.configure_multiple_op(op_path=[{\"op\": \"set\", \"path\": [...]}, {\"op\": \"delete\", \"path\": [...]}])"} + diff --git a/docs/development/vyos_api/configure-set.json b/docs/development/vyos_api/configure-set.json new file mode 100644 index 0000000..e99da8c --- /dev/null +++ b/docs/development/vyos_api/configure-set.json @@ -0,0 +1,2 @@ +{"command":"configure","operation":"set","description":"Set configuration values based on a path. Can accept single or multiple configuration paths.","endpoint":"/configure","method":"POST","request":{"payload":{"data":{"op":"set","path":["interfaces","ethernet","eth0","address","192.168.1.1/24"]},"key":"your-api-key"},"example":{"single_path":{"op":"set","path":["interfaces","ethernet","eth0","address","192.168.1.1/24"]},"multiple_paths":{"op":"set","path":[["interfaces","ethernet","eth0","address","192.168.1.1/24"],["interfaces","ethernet","eth0","description","Management"]]}}},"response":{"success":{"success":true,"data":{},"error":null},"error":{"success":false,"data":null,"error":"Configuration validation failed"}},"parameters":{"path":{"type":"array","required":true,"description":"Configuration path(s) as array of strings or array of path arrays for multiple configurations","examples":[["interfaces","ethernet","eth0","address","192.168.1.1/24"],[["interfaces","ethernet","eth0","address","192.168.1.1/24"],["interfaces","ethernet","eth0","description","Management"]]]}},"python_usage":"device.configure_set(path=[\"interfaces\", \"ethernet\", \"eth0\", \"address\", \"192.168.1.1/24\"])"} + diff --git a/docs/development/vyos_api/generate.json b/docs/development/vyos_api/generate.json new file mode 100644 index 0000000..bae9e16 --- /dev/null +++ b/docs/development/vyos_api/generate.json @@ -0,0 +1,2 @@ +{"command":"generate","operation":"generate","description":"Generate configuration elements such as SSH keys, certificates, etc.","endpoint":"/generate","method":"POST","request":{"payload":{"data":{"op":"generate","path":["ssh","client-key","/tmp/key_random"]},"key":"your-api-key"},"example":{"op":"generate","path":["ssh","client-key","/tmp/key_random"]}},"response":{"success":{"success":true,"data":"Generating public/private rsa key pair.\nYour identification has been saved in /tmp/key_random\nYour public key has been saved in /tmp/key_random.pub","error":null},"error":{"success":false,"data":null,"error":"Generation failed"}},"parameters":{"path":{"type":"array","required":true,"description":"Path specifying what to generate","example":["ssh","client-key","/tmp/key_random"]}},"python_usage":"device.generate(path=[\"ssh\", \"client-key\", \"/tmp/key_random\"])"} + diff --git a/docs/development/vyos_api/image-add.json b/docs/development/vyos_api/image-add.json new file mode 100644 index 0000000..068adbe --- /dev/null +++ b/docs/development/vyos_api/image-add.json @@ -0,0 +1,2 @@ +{"command":"image","operation":"add","description":"Add a VyOS system image from a URL or file.","endpoint":"/image","method":"POST","request":{"payload":{"data":{"op":"add","url":"https://example.com/vyos-image.iso"},"key":"your-api-key"},"example":{"from_url":{"op":"add","url":"https://example.com/vyos-image.iso"},"from_file":{"op":"add","file":"/path/to/local/image.iso"}}},"response":{"success":{"success":true,"data":{"status":"added","image":"vyos-image.iso"},"error":null},"error":{"success":false,"data":null,"error":"Failed to add image"}},"parameters":{"url":{"type":"string","required":false,"description":"URL of the image to download and add","format":"uri","example":"https://example.com/vyos-image.iso"},"file":{"type":"string","required":false,"description":"Local file path to the image","example":"/path/to/local/image.iso"},"path":{"type":"array","required":false,"description":"Additional path parameters","default":[],"example":[]}},"python_usage":"device.image_add(url=\"https://example.com/vyos-image.iso\")","notes":"Either url or file parameter must be provided."} + diff --git a/docs/development/vyos_api/image-delete.json b/docs/development/vyos_api/image-delete.json new file mode 100644 index 0000000..56ab796 --- /dev/null +++ b/docs/development/vyos_api/image-delete.json @@ -0,0 +1,2 @@ +{"command":"image","operation":"delete","description":"Delete a VyOS system image.","endpoint":"/image","method":"POST","request":{"payload":{"data":{"op":"delete","name":"image-name"},"key":"your-api-key"},"example":{"op":"delete","name":"image-name"}},"response":{"success":{"success":true,"data":{"status":"deleted","image":"image-name"},"error":null},"error":{"success":false,"data":null,"error":"Image not found or deletion failed"}},"parameters":{"name":{"type":"string","required":true,"description":"Name of the image to delete","example":"image-name"},"url":{"type":"string","required":false,"description":"Optional URL associated with the image","format":"uri"},"file":{"type":"string","required":false,"description":"Optional file path associated with the image"},"path":{"type":"array","required":false,"description":"Additional path parameters","default":[],"example":[]}},"python_usage":"device.image_delete(name=\"image-name\")"} + diff --git a/docs/development/vyos_api/index.json b/docs/development/vyos_api/index.json new file mode 100644 index 0000000..54a64c7 --- /dev/null +++ b/docs/development/vyos_api/index.json @@ -0,0 +1,2 @@ +{"title":"VyOS API Command Index","description":"Complete index of all VyOS REST API commands documented in this directory","version":"1.0.0","schema":"schema.json","commands":[{"file":"configure-set.json","command":"configure","operation":"set","python_method":"configure_set","description":"Set configuration values"},{"file":"configure-delete.json","command":"configure","operation":"delete","python_method":"configure_delete","description":"Delete configuration values"},{"file":"configure-multiple-op.json","command":"configure","operation":"multiple","python_method":"configure_multiple_op","description":"Execute multiple configuration operations atomically"},{"file":"retrieve-show-config.json","command":"retrieve","operation":"showConfig","python_method":"retrieve_show_config","description":"Retrieve configuration in show format"},{"file":"retrieve-return-values.json","command":"retrieve","operation":"returnValues","python_method":"retrieve_return_values","description":"Retrieve specific configuration values"},{"file":"show.json","command":"show","operation":"show","python_method":"show","description":"Execute show commands"},{"file":"generate.json","command":"generate","operation":"generate","python_method":"generate","description":"Generate configuration elements"},{"file":"reset.json","command":"reset","operation":"reset","python_method":"reset","description":"Reset configuration elements"},{"file":"config-file-save.json","command":"config-file","operation":"save","python_method":"config_file_save","description":"Save configuration to file"},{"file":"config-file-load.json","command":"config-file","operation":"load","python_method":"config_file_load","description":"Load configuration from file"},{"file":"reboot.json","command":"reboot","operation":"reboot","python_method":"reboot","description":"Reboot the device"},{"file":"poweroff.json","command":"poweroff","operation":"poweroff","python_method":"poweroff","description":"Power off the device"},{"file":"image-add.json","command":"image","operation":"add","python_method":"image_add","description":"Add VyOS system image"},{"file":"image-delete.json","command":"image","operation":"delete","python_method":"image_delete","description":"Delete VyOS system image"}],"statistics":{"total_commands":14,"command_types":{"configure":3,"retrieve":2,"show":1,"generate":1,"reset":1,"config-file":2,"reboot":1,"poweroff":1,"image":2}}} + diff --git a/docs/development/vyos_api/poweroff.json b/docs/development/vyos_api/poweroff.json new file mode 100644 index 0000000..1950691 --- /dev/null +++ b/docs/development/vyos_api/poweroff.json @@ -0,0 +1,2 @@ +{"command":"poweroff","operation":"poweroff","description":"Power off the VyOS device.","endpoint":"/poweroff","method":"POST","request":{"payload":{"data":{"op":"poweroff","path":["now"]},"key":"your-api-key"},"example":{"op":"poweroff","path":["now"]}},"response":{"success":{"success":true,"data":{"status":"powering off"},"error":null},"error":{"success":false,"data":null,"error":"Power off operation failed"}},"parameters":{"path":{"type":"array","required":false,"description":"Power off parameters, typically ['now']","default":["now"],"example":["now"]}},"python_usage":"device.poweroff(path=[\"now\"])","warning":"This operation will immediately power off the device."} + diff --git a/docs/development/vyos_api/reboot.json b/docs/development/vyos_api/reboot.json new file mode 100644 index 0000000..3ca92da --- /dev/null +++ b/docs/development/vyos_api/reboot.json @@ -0,0 +1,2 @@ +{"command":"reboot","operation":"reboot","description":"Reboot the VyOS device.","endpoint":"/reboot","method":"POST","request":{"payload":{"data":{"op":"reboot","path":["now"]},"key":"your-api-key"},"example":{"op":"reboot","path":["now"]}},"response":{"success":{"success":true,"data":{"status":"rebooting"},"error":null},"error":{"success":false,"data":null,"error":"Reboot operation failed"}},"parameters":{"path":{"type":"array","required":false,"description":"Reboot parameters, typically ['now']","default":["now"],"example":["now"]}},"python_usage":"device.reboot(path=[\"now\"])","warning":"This operation will immediately reboot the device."} + diff --git a/docs/development/vyos_api/reset.json b/docs/development/vyos_api/reset.json new file mode 100644 index 0000000..8418456 --- /dev/null +++ b/docs/development/vyos_api/reset.json @@ -0,0 +1,2 @@ +{"command":"reset","operation":"reset","description":"Reset configuration elements or system state.","endpoint":"/reset","method":"POST","request":{"payload":{"data":{"op":"reset","path":["conntrack-sync","internal-cache"]},"key":"your-api-key"},"example":{"op":"reset","path":["conntrack-sync","internal-cache"]}},"response":{"success":{"success":true,"data":"conntrack-sync is not configured!","error":null},"error":{"success":false,"data":null,"error":"Reset operation failed"}},"parameters":{"path":{"type":"array","required":false,"description":"Path specifying what to reset","default":[],"example":["conntrack-sync","internal-cache"]}},"python_usage":"device.reset(path=[\"conntrack-sync\", \"internal-cache\"])"} + diff --git a/docs/development/vyos_api/retrieve-return-values.json b/docs/development/vyos_api/retrieve-return-values.json new file mode 100644 index 0000000..c827b5d --- /dev/null +++ b/docs/development/vyos_api/retrieve-return-values.json @@ -0,0 +1,2 @@ +{"command":"retrieve","operation":"returnValues","description":"Retrieve and return specific configuration values for a given path.","endpoint":"/retrieve","method":"POST","request":{"payload":{"data":{"op":"returnValues","path":["interfaces","dummy","dum1","address"]},"key":"your-api-key"},"example":{"op":"returnValues","path":["interfaces","dummy","dum1","address"]}},"response":{"success":{"success":true,"data":["192.168.56.100/24"],"error":null},"error":{"success":false,"data":null,"error":"Path not found"}},"parameters":{"path":{"type":"array","required":true,"description":"Configuration path to retrieve values from","example":["interfaces","dummy","dum1","address"]}},"python_usage":"device.retrieve_return_values(path=[\"interfaces\", \"dummy\", \"dum1\", \"address\"])"} + diff --git a/docs/development/vyos_api/retrieve-show-config.json b/docs/development/vyos_api/retrieve-show-config.json new file mode 100644 index 0000000..bf5231f --- /dev/null +++ b/docs/development/vyos_api/retrieve-show-config.json @@ -0,0 +1,2 @@ +{"command":"retrieve","operation":"showConfig","description":"Retrieve and show the device configuration in show format.","endpoint":"/retrieve","method":"POST","request":{"payload":{"data":{"op":"showConfig","path":["system"]},"key":"your-api-key"},"example":{"op":"showConfig","path":["system"]}},"response":{"success":{"success":true,"data":{"config-management":{"commit-revisions":"100"},"host-name":"vyos-device","name-server":"eth0"},"error":null},"error":{"success":false,"data":null,"error":"Invalid path"}},"parameters":{"path":{"type":"array","required":false,"description":"Configuration path to retrieve, empty array for full config","default":[],"example":["system"]}},"python_usage":"device.retrieve_show_config(path=[\"system\"])"} + diff --git a/docs/development/vyos_api/schema.json b/docs/development/vyos_api/schema.json new file mode 100644 index 0000000..fb125b1 --- /dev/null +++ b/docs/development/vyos_api/schema.json @@ -0,0 +1,2 @@ +{"$schema":"http://json-schema.org/draft-07/schema#","$id":"https://github.com/vyos-contrib/pyvyos/docs/vyos-api/schema.json","title":"VyOS API Command Schema","description":"Schema definition for VyOS REST API commands","type":"object","definitions":{"apiRequest":{"type":"object","required":["command","op"],"properties":{"command":{"type":"string","description":"API endpoint command","enum":["configure","retrieve","show","generate","reset","config-file","reboot","poweroff","image"]},"op":{"type":"string","description":"Operation type","enum":["set","delete","showConfig","returnValues","show","generate","reset","save","load","reboot","poweroff","add","delete",""]},"path":{"oneOf":[{"type":"array","description":"Single configuration path","items":{"type":"string"}},{"type":"array","description":"Multiple configuration paths","items":{"type":"array","items":{"type":"string"}}},{"type":"array","description":"Multiple operations with paths","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["set","delete"]},"path":{"type":"array","items":{"type":"string"}}}]}]},"file":{"type":"string","description":"File path for file operations"},"url":{"type":"string","description":"URL for external resources","format":"uri"},"name":{"type":"string","description":"Resource name identifier"},"method":{"type":"string","description":"HTTP method","enum":["GET","POST","PUT","DELETE"],"default":"POST"}}},"apiResponse":{"type":"object","required":["success","data","error"],"properties":{"success":{"type":"boolean","description":"Whether the operation succeeded"},"data":{"description":"Response data (type varies by operation)","oneOf":[{"type":"object"},{"type":"array"},{"type":"string"},{"type":"null"}]},"error":{"oneOf":[{"type":"null"},{"type":"string"}],"description":"Error message if operation failed"}}}},"properties":{"request":{"$ref":"#/definitions/apiRequest"},"response":{"$ref":"#/definitions/apiResponse"}}} + diff --git a/docs/development/vyos_api/show.json b/docs/development/vyos_api/show.json new file mode 100644 index 0000000..3576e43 --- /dev/null +++ b/docs/development/vyos_api/show.json @@ -0,0 +1,2 @@ +{"command":"show","operation":"show","description":"Execute show commands to display system information.","endpoint":"/show","method":"POST","request":{"payload":{"data":{"op":"show","path":["system","image"]},"key":"your-api-key"},"example":{"op":"show","path":["system","image"]}},"response":{"success":{"success":true,"data":"Name Default boot Running\n------------------------ -------------- ---------\n1.5-rolling-202407300021 Yes Yes","error":null},"error":{"success":false,"data":null,"error":"Command not found"}},"parameters":{"path":{"type":"array","required":false,"description":"Command path for show operation","default":[],"example":["system","image"]}},"python_usage":"device.show(path=[\"system\", \"image\"])"} + -- cgit v1.2.3