Skip to main content

Inventory Device Variables

The Inventory Device Variables API provides access to device configuration parameters and settings variables for network devices. These endpoints allow you to retrieve and update device-specific configuration values, monitor pending changes, and manage parameter settings across your device inventory.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Variables API enables management of configuration parameters and variables for individual devices in your network inventory. This API category is essential for:

Device Configuration Management: Retrieve and modify configuration parameters for specific devices, including network settings, operational parameters, and custom variables.

Change Tracking: Monitor pending configuration changes before they are applied to devices, allowing for validation and approval workflows.

Parameter Filtering: Query specific parameters by variable name, parameter name, or short name to focus on relevant configuration data.

Bulk Operations: Update multiple device variables efficiently through structured API calls.

These endpoints work together to provide complete device parameter lifecycle management - from querying current values and pending changes to applying configuration updates. The API supports advanced filtering with wildcard patterns and provides options for retrieving additional metadata like timestamps and parameter details.

Endpoints

GET /inventory_device_variables/

Description: Retrieves configuration parameters and variables for a specific device. This endpoint allows you to query device settings, filter by parameter types, and check for pending configuration changes before they are applied to the device.

Use Cases:

  • Retrieve all configuration parameters for a specific device
  • Check for pending configuration changes before applying updates
  • Query specific parameters by variable name or parameter name
  • Monitor device configuration status and compliance

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=hostname,ip_address&pending=true&extra=true

Parameters:

Parameter Type In Required Description
parent_id integer query Yes The device ID to retrieve variables for
parameter__variable_name string query No Comma-separated list of specific variable names to retrieve (e.g., "hostname,ip_address,vlan_id")
parameter__name string query No Comma-separated list of parameter names to filter by
parameter__short_name string query No Comma-separated list of parameter short names to filter by
limit integer query No Number of results to return per page (default: 20, max: 100)
offset integer query No Starting index for pagination (default: 0)
pending boolean query No Include information about pending changes awaiting deployment
wildcard boolean query No Allow wildcard (*) characters in variable_name or parameter_name fields
force_update boolean query No Force refresh device settings from the device before returning data
extra boolean query No Include additional parameter metadata and details
dates boolean query No Include creation and modification timestamps

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=hostname,management_ip&pending=true&extra=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_id": 123,
      "variable_name": "hostname",
      "parameter_name": "System Hostname",
      "parameter_short_name": "hostname",
      "current_value": "sw-core-01",
      "pending_value": "sw-core-primary",
      "has_pending_changes": true,
      "data_type": "string",
      "description": "Device hostname for network identification",
      "last_updated": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T09:00:00Z",
      "is_required": true,
      "validation_pattern": "^[a-zA-Z0-9-]{1,63}$"
    },
    {
      "id": 1002,
      "parent_id": 123,
      "variable_name": "management_ip",
      "parameter_name": "Management IP Address",
      "parameter_short_name": "mgmt_ip",
      "current_value": "192.168.1.10",
      "pending_value": null,
      "has_pending_changes": false,
      "data_type": "ipv4",
      "description": "IP address for device management access",
      "last_updated": "2024-01-10T14:22:00Z",
      "created_at": "2024-01-01T09:00:00Z",
      "is_required": true,
      "validation_pattern": "^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns device variables and parameters
400 Bad Request - Invalid parameters or missing required parent_id
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified parent_id does not exist
500 Internal Server Error - Unable to retrieve device variables

PUT /inventory_device_variables/{parent_id}/

Description: Updates configuration parameters and variables for a specific device. This endpoint allows you to modify device settings by providing new values for one or more parameters. Changes may be applied immediately or staged as pending changes depending on the device configuration.

Use Cases:

  • Update device configuration parameters (hostname, IP addresses, VLANs)
  • Apply bulk configuration changes to a device
  • Stage configuration changes for later deployment
  • Modify device-specific operational settings

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_variables/123/

Parameters:

Parameter Type In Required Description
parent_id integer path Yes The device ID to update variables for
data string body Yes JSON payload containing parameter updates

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": [
      {
        "variable_name": "hostname",
        "value": "sw-core-primary",
        "apply_immediately": false
      },
      {
        "variable_name": "management_vlan",
        "value": "100",
        "apply_immediately": true
      }
    ]
  }'

Example Request Body:

{
  "variables": [
    {
      "variable_name": "hostname",
      "value": "sw-core-primary",
      "apply_immediately": false,
      "comment": "Updated hostname for primary core switch"
    },
    {
      "variable_name": "management_vlan",
      "value": "100",
      "apply_immediately": true,
      "comment": "Changed management VLAN to 100"
    },
    {
      "variable_name": "snmp_community",
      "value": "secure_community_string",
      "apply_immediately": false,
      "encrypted": true
    }
  ],
  "batch_comment": "Monthly configuration update",
  "schedule_deployment": "2024-01-20T02:00:00Z"
}

Example Response:

{
  "success": true,
  "updated_variables": [
    {
      "variable_name": "hostname",
      "previous_value": "sw-core-01",
      "new_value": "sw-core-primary",
      "status": "pending",
      "scheduled_for": "2024-01-20T02:00:00Z"
    },
    {
      "variable_name": "management_vlan",
      "previous_value": "10",
      "new_value": "100",
      "status": "applied",
      "applied_at": "2024-01-15T15:45:00Z"
    },
    {
      "variable_name": "snmp_community",
      "previous_value": "[ENCRYPTED]",
      "new_value": "[ENCRYPTED]",
      "status": "pending",
      "scheduled_for": "2024-01-20T02:00:00Z"
    }
  ],
  "batch_id": "batch_2024011515450123",
  "total_updated": 3,
  "pending_count": 2,
  "applied_count": 1,
  "next_deployment": "2024-01-20T02:00:00Z"
}

Response Codes:

Status Description
200 Success - Variables updated successfully
400 Bad Request - Invalid variable data or validation errors
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified parent_id does not exist
422 Unprocessable Entity - Variable validation failed
500 Internal Server Error - Unable to update device variables

Common Use Cases

Use Case 1: Configuration Compliance Check

Query all device parameters to verify compliance with organizational standards, checking for pending changes and validating current configurations against policy requirements.

# Get all variables with pending status and extra details
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&pending=true&extra=true&dates=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Network Parameter Updates

Update critical network parameters like hostnames, management IPs, and VLAN configurations as part of network reorganization or device migration.

# Update hostname and management IP for device relocation
curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables":[{"variable_name":"hostname","value":"sw-new-location"},{"variable_name":"management_ip","value":"10.1.1.50"}]}'

Use Case 3: Security Configuration Management

Retrieve and update security-related parameters like SNMP communities, access control lists, and authentication settings across device inventory.

Use Case 4: Bulk Configuration Deployment

Stage multiple configuration changes for scheduled deployment during maintenance windows, allowing for coordinated network-wide updates.

Use Case 5: Parameter Monitoring and Alerting

Monitor specific device parameters for changes and compliance, integrating with monitoring systems to track configuration drift.

Best Practices

Parameter Filtering: Use specific parameter filters (parameter__variable_name, parameter__name) to reduce response size and improve performance when working with devices that have many configuration parameters.

Pagination: Always implement pagination when querying devices with extensive configuration parameters. Use limit and offset parameters to manage large result sets efficiently.

Change Management: Leverage the pending parameter to review configuration changes before deployment. This allows for approval workflows and change validation processes.

Forced Updates: Use force_update=true sparingly as it triggers real-time device polling. Reserve this for critical situations where you need the most current device state.

Error Handling: Implement robust error handling for validation failures (422) and device connectivity issues. Configuration updates may fail due to device-specific constraints or network connectivity problems.

Security Considerations: Be cautious when updating security-related parameters. Always verify that changes don't lock you out of device management access, especially when modifying IP addresses or authentication settings.

Batch Operations: Group related parameter updates into single API calls to maintain configuration consistency and reduce the number of device interactions required.

Back to top