feat: v0.4.0 - Architecture refactor, bug fixes, and quality improvementsfeat/architecture-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

19 files changed, 293 insertions, 0 deletions

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_<do>_when_<condition>`
+- 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\"])"}
+