hier-config-api
REST API for hier_config network configuration management.
Overview
This FastAPI-based REST API provides a comprehensive interface to the hier_config library, enabling network engineers to:
- Compare and diff network configurations
- Generate remediation and rollback commands
- Analyze configuration changes across multiple devices
- Validate configurations for different network platforms
Features
- Configuration Operations: Parse, compare, merge, and search network configurations
- Remediation Workflows: Generate remediation and rollback configurations with tag-based filtering
- Multi-Device Reporting: Aggregate and analyze configuration changes across device fleets
- Platform Support: Cisco IOS, Cisco NX-OS, Cisco IOS-XR, Juniper Junos, Arista EOS
- Batch Processing: Process multiple devices in parallel
- Export Formats: JSON, CSV, YAML
Quick Start
Installation
# Clone the repository
git clone https://github.com/netdevops/hier-config-api.git
cd hier-config-api
# Install dependencies with poetry
poetry install
# Run the API server
poetry run uvicorn hier_config_api.main:app --reload
Access the API Documentation
Once the server is running, access the interactive API documentation at:
- Swagger UI: http://localhost:8000/api/docs
- ReDoc: http://localhost:8000/api/redoc
API Endpoints
Configuration Operations
Parse Configuration
POST /api/v1/configs/parse
Parse raw configuration text into structured format.
Example:
curl -X POST http://localhost:8000/api/v1/configs/parse \
-H "Content-Type: application/json" \
-d '{
"platform": "cisco_ios",
"config_text": "hostname router1\ninterface GigabitEthernet0/0\n ip address 192.168.1.1 255.255.255.0"
}'
Compare Configurations
POST /api/v1/configs/compare
Compare running and intended configurations to show differences.
Example:
curl -X POST http://localhost:8000/api/v1/configs/compare \
-H "Content-Type: application/json" \
-d '{
"platform": "cisco_ios",
"running_config": "hostname old-router",
"intended_config": "hostname new-router"
}'
Predict Future Configuration
POST /api/v1/configs/predict
Predict configuration state after applying commands.
Merge Configurations
POST /api/v1/configs/merge
Merge multiple configuration snippets into one.
Search Configuration
POST /api/v1/configs/search
Search configuration using pattern matching.
Remediation Workflows
Generate Remediation
POST /api/v1/remediation/generate
Generate remediation and rollback configurations.
Example:
curl -X POST http://localhost:8000/api/v1/remediation/generate \
-H "Content-Type: application/json" \
-d '{
"platform": "cisco_ios",
"running_config": "hostname router1\ninterface GigabitEthernet0/0\n ip address 192.168.1.1 255.255.255.0",
"intended_config": "hostname router2\ninterface GigabitEthernet0/0\n ip address 192.168.1.2 255.255.255.0"
}'
Response:
{
"remediation_id": "abc-123",
"platform": "cisco_ios",
"remediation_config": "no hostname router1\nhostname router2\ninterface GigabitEthernet0/0\n no ip address 192.168.1.1 255.255.255.0\n ip address 192.168.1.2 255.255.255.0",
"rollback_config": "...",
"summary": {
"additions": 3,
"deletions": 2,
"modifications": 0
},
"tags": {}
}
Apply Tags to Remediation
POST /api/v1/remediation/{remediation_id}/tags
Apply tag rules to an existing remediation.
Filter Remediation by Tags
GET /api/v1/remediation/{remediation_id}/filter?include_tags=safe&exclude_tags=risky
Filter remediation commands by tags.
Multi-Device Reporting
Create Report
POST /api/v1/reports
Create a multi-device configuration report.
Example:
curl -X POST http://localhost:8000/api/v1/reports \
-H "Content-Type: application/json" \
-d '{
"remediations": [
{
"device_id": "router1",
"platform": "cisco_ios",
"running_config": "...",
"intended_config": "..."
},
{
"device_id": "router2",
"platform": "cisco_ios",
"running_config": "...",
"intended_config": "..."
}
]
}'
Get Report Summary
GET /api/v1/reports/{report_id}/summary
Get aggregated statistics for a report.
Get Report Changes
GET /api/v1/reports/{report_id}/changes?tag=safe&min_devices=2
Get detailed change analysis showing which changes appear across multiple devices.
Export Report
GET /api/v1/reports/{report_id}/export?format=json|csv|yaml
Export report in specified format.
Platform Information
List Platforms
GET /api/v1/platforms
List all supported network platforms.
Get Platform Rules
GET /api/v1/platforms/{platform}/rules
Get platform-specific configuration rules.
Validate Configuration
POST /api/v1/platforms/{platform}/validate
Validate configuration for a specific platform.
Batch Operations
Create Batch Job
POST /api/v1/batch/remediation
Create a batch remediation job for multiple devices.
Get Batch Job Status
GET /api/v1/batch/jobs/{job_id}
Get the status and progress of a batch job.
Get Batch Job Results
GET /api/v1/batch/jobs/{job_id}/results
Get the results of a completed batch job.
Development
Running Tests
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov=hier_config_api --cov-report=html
# Run specific test file
poetry run pytest tests/test_configs.py -v
Code Quality
# Run ruff linter
poetry run ruff check .
# Run ruff formatter
poetry run ruff format .
# Run mypy type checker
poetry run mypy hier_config_api
# Run all linters
poetry run ruff check . && poetry run mypy hier_config_api
Supported Platforms
- Cisco IOS (
cisco_ios) - Cisco NX-OS (
cisco_nxos) - Cisco IOS-XR (
cisco_iosxr) - Juniper Junos (
juniper_junos) - Arista EOS (
arista_eos) - Generic (
generic)
Architecture
hier-config-api/
├── hier_config_api/
│ ├── models/ # Pydantic models for request/response validation
│ ├── routers/ # API endpoint definitions
│ ├── services/ # Business logic layer
│ ├── utils/ # Utility functions (storage, etc.)
│ └── main.py # FastAPI application entry point
├── tests/ # Pytest test suite
└── pyproject.toml # Project configuration
License
See LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Related Projects
- hier_config - The core library powering this API
Metadata
Release files for hier-config-api 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hier_config_api-0.1.0.tar.gz | 19.6 kB | Without provenance | Details for hier_config_api-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hier_config_api-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for hier_config_api-0.1.0-py3-none-any.whl |
Total release size: 44.7 kB
Release files / hier_config_api-0.1.0.tar.gz
| Download URL | hier_config_api-0.1.0.tar.gz |
|---|---|
| Size | 19.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d3ae1e4846201d88fa8b64f619d8b6fdf55b46cb35334d24c248e3ad4936c15f
|
|
BLAKE2b-256 checksum How to use checksums |
bda872c526bec3fb37916d4207c053b880218f453a37782975fde72a3344b826
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.2 CPython/3.11.14 Darwin/25.2.0
|
Release files / hier_config_api-0.1.0-py3-none-any.whl
| Download URL | hier_config_api-0.1.0-py3-none-any.whl |
|---|---|
| Size | 25.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d9f6ed2bcd67d83c2fa7f137a1ee5570d6a12f898353f059c811b67e4447f32
|
|
BLAKE2b-256 checksum How to use checksums |
3629e1849a0df1137da492aa8148229045fc8b8d3e868b61f16e36e0ac6bc7ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.3.2 CPython/3.11.14 Darwin/25.2.0
|
Security for hier-config-api 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.