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

This project follows the same development, testing, and linting standards as hier_config. All checks are driven by scripts/build.py:

# Full lint + test suite (what CI runs)
poetry run python scripts/build.py lint-and-test

# Lint only (ruff format + check, mypy, pyright, pylint, yamllint, flynt — in parallel)
poetry run python scripts/build.py lint

# Lint with auto-fixes applied
poetry run python scripts/build.py lint --fix

# Tests with coverage (95% minimum enforced)
poetry run python scripts/build.py pytest --coverage

Running Tests

# Run all tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_configs.py -v

# Run a single test
poetry run pytest tests/test_configs.py::test_parse_config -v

Code Quality Standards

• ruff: select = ["ALL"] with preview rules, line length 88; formatting via ruff format
• mypy: strict mode with the pydantic plugin
• pyright: typeCheckingMode = "strict"
• pylint: extension plugins + pylint_pydantic, for rules not covered by ruff
• yamllint / flynt: YAML style and f-string enforcement
• pytest: flat function-based tests with full type annotations; 95% coverage floor

Never loosen the lint or coverage configuration to make a change pass.

Releasing

Releases are driven by two GitHub Actions workflows and require repository admin permission:

1. Run the Prepare Release workflow (Actions → Prepare Release → Run workflow), choosing the branch to release from in the branch dropdown and the version bump type (major, minor, patch, or prerelease). The workflow bumps the version in pyproject.toml, opens a release/vX.Y.Z pull request against the chosen branch, and creates a draft GitHub release tagged vX.Y.Z targeting that branch.
2. Merge the release pull request.
3. Publish the draft release. Publishing fires the Release workflow, which builds the package and uploads it to PyPI automatically.

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