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

1 files changed, 78 insertions, 0 deletions

diff --git a/docs/vyos-api.md b/docs/vyos-api.md
new file mode 100644
index 0000000..33a443f
--- /dev/null
+++ b/docs/vyos-api.md
@@ -0,0 +1,78 @@
+# VyOS API Command Reference
+
+The JSON definitions for each VyOS REST API command supported by PyVyOS are located in `docs/development/vyos_api/`.
+
+## Location
+
+All JSON specification files are stored in: **`docs/development/vyos_api/`**
+
+These JSONs are reference documentation and are:
+- Used for API documentation generation
+- Available for validation and testing
+- Not packaged with the library (reference only)
+
+## Files
+
+- `schema.json` - JSON Schema definition for all API commands
+- Individual command files:
+  - `configure-set.json` - Set configuration values
+  - `configure-delete.json` - Delete configuration values
+  - `configure-multiple-op.json` - Execute multiple operations atomically
+  - `retrieve-show-config.json` - Retrieve configuration in show format
+  - `retrieve-return-values.json` - Retrieve specific configuration values
+  - `show.json` - Execute show commands
+  - `generate.json` - Generate configuration elements (SSH keys, etc.)
+  - `reset.json` - Reset configuration elements
+  - `config-file-save.json` - Save configuration to file
+  - `config-file-load.json` - Load configuration from file
+  - `reboot.json` - Reboot the device
+  - `poweroff.json` - Power off the device
+  - `image-add.json` - Add VyOS system image
+  - `image-delete.json` - Delete VyOS system image
+
+## Structure
+
+Each JSON file follows this structure:
+
+```json
+{
+  "command": "command-name",
+  "operation": "operation-name",
+  "description": "Description of what the command does",
+  "endpoint": "/endpoint-path",
+  "method": "HTTP_METHOD",
+  "request": {
+    "payload": { ... },
+    "example": { ... }
+  },
+  "response": {
+    "success": { ... },
+    "error": { ... }
+  },
+  "parameters": { ... },
+  "python_usage": "device.method_name(...)"
+}
+```
+
+## Usage
+
+These JSON files can be used for:
+- API documentation generation
+- Request validation
+- Response schema validation
+- Client library code generation
+- Testing and mocking
+
+## JSON Schema
+
+The `schema.json` file defines the complete structure for all API commands and can be used with JSON Schema validators.
+
+## Path Parameter Handling
+
+**Important:** The `path` parameter handling varies by command:
+
+- **config-file commands** (`save`, `load`): The VyOS API requires `path` to be present in the payload, even if empty (`[]`). PyVyOS handles this automatically.
+- **Other commands**: When `path` is empty or not provided, it may be omitted from the payload for cleaner requests.
+
+See individual JSON files in `docs/development/vyos_api/` for specific parameter requirements.
+