Inventory Device Name Variables

The Inventory Device Name Variables API provides endpoints to manage and retrieve device configuration parameters and settings for specific devices in your inventory. These endpoints allow you to query device variables by device name and update device configurations, making it essential for device management, configuration automation, and monitoring pending changes across your infrastructure.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Variables API enables comprehensive management of device-specific configuration parameters and variables within your network inventory. This API category is specifically designed for scenarios where you need to interact with device settings using the device name as the primary identifier.

Key Capabilities:

Device Parameter Retrieval: Query specific configuration variables and parameters for named devices
Configuration Management: Update device settings and monitor pending configuration changes
Flexible Filtering: Filter parameters by variable names, parameter names, or short names
Real-time Status: Check for pending settings and force updates when needed
Detailed Metadata: Access additional parameter information including timestamps and extra details

Common Integration Scenarios:

Network automation tools that need to verify or update device configurations
Monitoring systems that track configuration drift and pending changes
Bulk configuration management across multiple devices
Compliance reporting that requires detailed parameter history and metadata

This API is particularly useful for network administrators, DevOps engineers, and automation systems that manage large-scale device deployments where configuration consistency and change tracking are critical.

Endpoints

GET /inventory_device_name_variables/

Description: Retrieves configuration parameters and variables for devices in your inventory, filtered by device name. This endpoint is essential for querying current device settings, checking for pending configuration changes, and retrieving detailed parameter metadata. It supports flexible filtering options to target specific parameters or parameter types.

Use Cases:

Monitor configuration status across multiple devices
Retrieve specific parameters for compliance reporting
Check for pending configuration changes before maintenance
Audit device settings and parameter history

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=router-01&parameter__variable_name=hostname,interface_config&pending=true&limit=50

Parameters:

Parameter	Type	In	Required	Description
parent__name	string	query	Yes	The device name to filter by. This identifies the specific device whose parameters you want to retrieve
parameter__variable_name	string	query	No	Comma-separated list of parameter variable names to retrieve (e.g., "hostname,snmp_community,vlan_config")
parameter__name	string	query	No	Comma-separated list of parameter names to retrieve for more human-readable filtering
parameter__short_name	string	query	No	Comma-separated list of parameter short names for abbreviated parameter identification
limit	integer	query	No	Number of results to return per page (default varies, recommended: 50-100)
offset	integer	query	No	Starting index for pagination (use with limit for browsing large result sets)
pending	boolean	query	No	Set to true to only show devices with pending configuration changes
wildcard	boolean	query	No	Set to true to use wildcard (*) characters in variable_name or parameter name fields
force_update	boolean	query	No	Set to true to force refresh device settings from the actual device before returning results
extra	boolean	query	No	Set to true to include additional metadata and detailed parameter information
dates	boolean	query	No	Set to true to include timestamp information for parameters (created, modified, etc.)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=router-01&parameter__variable_name=hostname,interface_speed&extra=true&dates=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name_variables/?limit=20&offset=20&parent__name=router-01",
  "previous": null,
  "results": [
    {
      "id": 1247,
      "device_name": "router-01",
      "parameter_name": "System Hostname",
      "parameter_short_name": "hostname",
      "variable_name": "hostname",
      "current_value": "router-01.datacenter.company.com",
      "pending_value": null,
      "data_type": "string",
      "is_pending": false,
      "last_updated": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-10T09:15:00Z",
      "extra_info": {
        "validation_rule": "^[a-zA-Z0-9\\.-]+$",
        "restart_required": false,
        "category": "system"
      }
    },
    {
      "id": 1248,
      "device_name": "router-01",
      "parameter_name": "Interface Speed",
      "parameter_short_name": "int_speed",
      "variable_name": "interface_speed",
      "current_value": "1000",
      "pending_value": "10000",
      "data_type": "integer",
      "is_pending": true,
      "last_updated": "2024-01-16T14:22:00Z",
      "created_at": "2024-01-10T09:15:00Z",
      "extra_info": {
        "unit": "Mbps",
        "valid_values": [100, 1000, 10000],
        "restart_required": true,
        "category": "network"
      }
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns the device parameters and variables
400	Bad Request - Missing required parent__name parameter or invalid query parameters
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified name does not exist
500	Internal Server Error - Server error during parameter retrieval

PUT /inventory_device_name_variables/{parent__name}/

Description: Updates configuration parameters and variables for a specific device identified by name. This endpoint allows you to modify device settings, apply pending configurations, and bulk update multiple parameters in a single operation. It's the primary method for programmatic device configuration management.

Use Cases:

Apply configuration changes to devices through automation
Bulk update multiple parameters for a device
Set device configurations as part of deployment pipelines
Synchronize device settings across environments

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_variables/router-01/

Parameters:

Parameter	Type	In	Required	Description
parent__name	string	path	Yes	The device name in the URL path identifying which device to update
data	string	body	Yes	JSON payload containing the parameter updates to apply to the device

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_variables/router-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [
      {
        "variable_name": "hostname",
        "value": "router-01.newdomain.com"
      },
      {
        "variable_name": "interface_speed", 
        "value": "10000"
      },
      {
        "variable_name": "snmp_community",
        "value": "production_read_v2"
      }
    ],
    "apply_immediately": false,
    "validate_only": false
  }'

Example Request Body:

{
  "parameters": [
    {
      "variable_name": "hostname",
      "value": "router-01.production.company.com",
      "force_update": false
    },
    {
      "variable_name": "interface_speed",
      "value": "10000",
      "force_update": true
    },
    {
      "variable_name": "vlan_config",
      "value": "100,200,300",
      "force_update": false
    }
  ],
  "apply_immediately": false,
  "validate_only": false,
  "backup_current": true
}

Example Response:

{
  "status": "success",
  "device_name": "router-01",
  "updated_parameters": [
    {
      "variable_name": "hostname",
      "previous_value": "router-01.staging.company.com",
      "new_value": "router-01.production.company.com",
      "status": "pending",
      "requires_restart": false
    },
    {
      "variable_name": "interface_speed", 
      "previous_value": "1000",
      "new_value": "10000",
      "status": "applied",
      "requires_restart": true
    },
    {
      "variable_name": "vlan_config",
      "previous_value": "100,200",
      "new_value": "100,200,300",
      "status": "pending",
      "requires_restart": false
    }
  ],
  "summary": {
    "total_parameters": 3,
    "applied_immediately": 1,
    "pending_application": 2,
    "validation_errors": 0,
    "restart_required": true
  },
  "backup_id": "backup_router-01_20240116_142500",
  "timestamp": "2024-01-16T14:25:00Z"
}

Response Codes:

Status	Description
200	Success - Parameters updated successfully
400	Bad Request - Invalid parameter data or validation errors
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified name does not exist
409	Conflict - Parameter update conflicts with existing pending changes
500	Internal Server Error - Server error during parameter update

Common Use Cases

Use Case 1: Configuration Compliance Monitoring

Monitor device configurations across your infrastructure to ensure compliance with organizational standards. Use the GET endpoint with specific parameter filters to check critical settings like SNMP communities, NTP servers, and security policies across all devices.

# Check SNMP configuration across devices
GET /inventory_device_name_variables/?parameter__variable_name=snmp_community,snmp_version&extra=true

Use Case 2: Automated Device Deployment

During device provisioning, use the PUT endpoint to apply standardized configurations to new devices. This ensures consistent setup across your infrastructure and reduces manual configuration errors.

Use Case 3: Pending Change Management

Before maintenance windows, use the GET endpoint with pending=true to identify all devices with pending configuration changes, then coordinate the application of these changes during scheduled maintenance.

Use Case 4: Configuration Drift Detection

Regularly query device parameters and compare against your configuration management database to detect unauthorized changes or configuration drift across your network infrastructure.

Use Case 5: Bulk Parameter Updates

Use the PUT endpoint to update multiple related parameters simultaneously, such as updating VLAN configurations, routing parameters, and security settings as part of a coordinated network change.

Best Practices

Use Pagination Effectively: For large inventories, always use the limit parameter (recommended: 50-100 items per page) and implement proper pagination handling to avoid timeouts and excessive memory usage.
Leverage Filtering: Use specific parameter filters (parameter__variable_name, parameter__name) to reduce response size and improve performance when you only need specific configuration data.
Handle Pending Changes: Always check the is_pending field in responses and consider using the pending=true query parameter to identify devices requiring attention before making new changes.
Force Updates Judiciously: Use force_update=true sparingly as it triggers real-time device communication, which can impact performance. Reserve it for critical operations where you need the absolute latest data.
Implement Proper Error Handling: Always handle 404 responses when querying by device name, as devices may be renamed, decommissioned, or temporarily unavailable.
Use Validation Mode: When updating parameters, consider using validate_only=true in your request to test parameter changes before applying them, especially in production environments.
Monitor Rate Limits: Be mindful of API rate limits when making bulk operations. Implement exponential backoff and respect any rate limiting headers in responses.
Backup Before Changes: Always set backup_current=true when updating critical device parameters to enable quick rollback if issues occur.