Skip to main content

Inventory Device Name Variables

The Inventory Device Name Variables API provides access to device configuration parameters and settings within the Zequenze control system. These endpoints allow you to retrieve and update device-specific variables by device name, making it easy to manage configuration parameters across your device inventory programmatically.

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 management of device configuration settings and parameters through a device-centric approach. This API category is designed for scenarios where you need to:

  • Retrieve device settings by device name rather than device ID, making integration easier when you know device names but not internal IDs
  • Manage configuration parameters including variable names, values, types, and metadata
  • Monitor pending changes to device configurations before they are applied
  • Bulk parameter operations using comma-separated lists for efficient data retrieval
  • Track configuration history with date information and extra metadata

The endpoints work together to provide a complete device configuration management workflow. The GET endpoint allows you to query current device settings with flexible filtering options, while the PUT endpoint enables updates to device configurations. Both endpoints support advanced features like wildcard matching, forced updates, and detailed metadata retrieval.

Key concepts include:

  • Variable Names: Internal parameter identifiers used by the system
  • Parameter Names: Human-readable names for configuration settings
  • Short Names: Abbreviated parameter identifiers for compact displays
  • Pending Status: Indicates whether configuration changes are waiting to be applied
  • Extra Information: Additional metadata and extended parameter details

Endpoints

GET /inventory_device_name_variables/

Description: Retrieves device configuration parameters and settings filtered by device name. This endpoint is essential for querying current device configurations, monitoring pending changes, and extracting specific parameter sets. It supports flexible filtering by parameter names, variable names, or short names, with optional wildcard matching for pattern-based queries.

Use Cases:

  • Retrieve all configuration parameters for a specific device by name
  • Monitor devices with pending configuration changes across your inventory
  • Extract specific parameters (like network settings or thresholds) from multiple devices
  • Audit device configurations with historical date information

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=router-01&parameter__variable_name=network_config,snmp_community&extra=true&dates=true

Parameters:

Parameter Type In Required Description
parent__name string query Yes Filter settings by device name. This identifies which device's parameters to retrieve
parameter__variable_name string query No Comma-separated list of parameter variable names to retrieve (e.g., "network_ip,snmp_port")
parameter__name string query No Comma-separated list of human-readable parameter names to retrieve
parameter__short_name string query No Comma-separated list of parameter short names for compact identification
limit integer query No Number of results to return per page (default pagination limit applies)
offset integer query No Starting index for paginated results (use with limit for pagination)
pending boolean query No Filter to show only parameters with pending changes when set to true
wildcard boolean query No Enable wildcard (*) matching in variable_name or parameter name fields
force_update boolean query No Force refresh of device settings from the device before returning data
extra boolean query No Include additional metadata and extended parameter information
dates boolean query No Include creation/modification timestamps for configuration tracking

cURL Example:

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

Example Response:

{
  "count": 15,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name_variables/?limit=10&offset=10&parent__name=router-01",
  "previous": null,
  "results": [
    {
      "id": 1247,
      "name": "Network Configuration",
      "variable_name": "network_config",
      "value": "192.168.1.100/24",
      "type": "ipv4_network",
      "short_name": "net_cfg",
      "extra": true,
      "extra_value": "gateway=192.168.1.1,dns=8.8.8.8",
      "pending": false
    },
    {
      "id": 1248,
      "name": "Device Name",
      "variable_name": "device_name",
      "value": "router-01",
      "type": "string",
      "short_name": "name",
      "extra": false,
      "extra_value": null,
      "pending": false
    },
    {
      "id": 1249,
      "name": "SNMP Community",
      "variable_name": "snmp_community",
      "value": "private_updated",
      "type": "string",
      "short_name": "snmp",
      "extra": false,
      "extra_value": null,
      "pending": true
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns device parameters matching the specified criteria
400 Bad Request - Missing required parent__name parameter or invalid query parameters
401 Unauthorized - Invalid or missing authentication token
404 Not Found - No device found with the specified name

PUT /inventory_device_name_variables/{parent__name}/

Description: Updates device configuration parameters for the specified device name. This endpoint allows you to modify device settings by sending parameter data in the request body. The operation updates existing parameters or creates new ones as needed, with changes typically marked as pending until applied to the actual device.

Use Cases:

  • Update network configuration settings for a specific device
  • Modify SNMP parameters, thresholds, or operational settings
  • Bulk update multiple parameters in a single API call
  • Apply configuration templates to devices by name

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 name of the device whose parameters will be updated
data string body Yes JSON payload containing parameter updates with variable names and new values

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": "snmp_community",
        "value": "new_community_string"
      },
      {
        "variable_name": "poll_interval",
        "value": "300"
      }
    ]
  }'

Example Response:

{
  "id": 1249,
  "name": "SNMP Community",
  "variable_name": "snmp_community",
  "value": "new_community_string",
  "type": "string",
  "short_name": "snmp",
  "extra": false,
  "extra_value": null,
  "pending": true
}

Response Codes:

Status Description
200 Success - Parameters updated successfully
400 Bad Request - Invalid parameter data or malformed request body
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist
422 Unprocessable Entity - Parameter validation failed

Common Use Cases

Use Case 1: Device Configuration Audit

Query all parameters for specific devices to perform configuration audits or compliance checks. Use the extra and dates parameters to get complete configuration history.

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=critical-router&extra=true&dates=true"

Use Case 2: Bulk Network Configuration Updates

Update network settings across multiple devices by iterating through device names and applying consistent configuration parameters.

Use Case 3: Pending Changes Monitoring

Monitor devices with pending configuration changes to track deployment status and ensure changes are properly applied.

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=router-01&pending=true"

Use Case 4: Parameter Pattern Matching

Use wildcard filtering to find all parameters matching specific patterns, useful for discovering related configuration settings across devices.

Use Case 5: Configuration Template Deployment

Apply standardized configuration templates to devices by updating multiple parameters simultaneously through the PUT endpoint.

Best Practices

  • Use device names consistently - Ensure device names in your API calls match exactly with those stored in the system, as the parent__name parameter is case-sensitive
  • Implement proper pagination - For devices with many parameters, use limit and offset parameters to handle large result sets efficiently
  • Monitor pending status - Always check the pending field in responses to understand which changes haven't been applied to physical devices yet
  • Leverage wildcard filtering - Use the wildcard parameter when searching for parameter patterns, but be cautious of performance impact on large datasets
  • Cache configuration data - Device parameters typically don't change frequently, so implement appropriate caching strategies to reduce API calls
  • Handle force_update carefully - The force_update parameter triggers real device communication, which may be slow; use sparingly and implement appropriate timeouts
  • Validate parameter types - Check the type field in responses to ensure you're sending appropriately formatted values in PUT requests
  • Use specific parameter filters - Instead of retrieving all parameters, use parameter__variable_name or parameter__name filters to get only needed data
  • Implement retry logic - Network devices may be temporarily unreachable; implement exponential backoff for failed requests
Back to top