Inventory Device Name Variables

ManageThe 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 variablesand update device configurations, making it essential for inventorydevice devices,management, allowingconfiguration retrievalautomation, and updatesmonitoring ofpending device-specificchanges parameteracross configurations.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/

RetrieveDescription: Retrieves configuration parameters and variables for devices in your inventory, filtered by device parameter variables and settings for inventory devices.name. This endpoint allowsis essential for querying current device settings, checking for pending configuration changes, and retrieving detailed parameter metadata. It supports flexible filtering byoptions 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 namesettings and specificparameter parameters,history with options

Full forURL additionalExample:

metadata

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

Parameters:

Parameter	Type	In	Required	Description
parent__name	string	query	Yes	FilterThe settingdevice byname 'parentto (device)filter name'by. fieldThis identifies the specific device whose parameters you want to retrieve
parameter__variable_name	string	query	No	Comma Comma-separated list of parameter 'variable names'names to retrieve (e.g., "hostname,snmp_community,vlan_config")
parameter__name	string	query	No	Comma Comma-separated list of parameter 'names'names to retrieve for more human-readable filtering
parameter__short_name	string	query	No	Comma Comma-separated list of parameter 'short-names'short tonames retrievefor abbreviated parameter identification
limit	integer	query	No	Number of results to return per page (default varies, recommended: 50-100)
offset	integer	query	No	The initialStarting index fromfor whichpagination to(use returnwith thelimit resultsfor browsing large result sets)
pending	boolean	query	No	ReportSet ifto thetrue deviceto haveonly show devices with pending settingsconfiguration changes
wildcard	boolean	query	No	UseSet to true to use wildcard ('*') charactercharacters in 'variable name'variable_name or 'parameter name'name fields
force_update	boolean	query	No	ForceSet updateto true to force refresh device settings before gettingfrom the requestedactual informationdevice before returning results
extra	boolean	query	No	ShowSet additional/extrato true to include additional metadata and detailed parameter information of the parameter
dates	boolean	query	No	ShowSet dateto true to include timestamp information offor theparameters parameter(s)(created, modified, etc.)

ExamplecURL Request:Example:

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

Example Response:

{
  "count": 2,25,
  "next": null,"https://control.zequenze.com/api/v1/inventory_device_name_variables/?limit=20&offset=20&parent__name=router-01",
  "previous": null,
  "results": [
    {
      "id": 1,1247,
      "parent_name"device_name": "router-01",
      "parameter"parameter_name": {"System Hostname",
      "parameter_short_name": "hostname",
      "variable_name": "hostname",
      "name": "System Hostname",
        "short_name": "hostname",
        "value"current_value": "router-01.datacenter.company.com",
      "pending_value": null,
      "data_type": "string"
      },
      "pending"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",
        "editable": true
      }
    },
    {
      "id": 2,1248,
      "parent_name"device_name": "router-01",
      "parameter"parameter_name": {"Interface Speed",
      "parameter_short_name": "int_speed",
      "variable_name": "ip_address"interface_speed",
      "name"current_value": "Management IP Address"1000",
      "short_name"pending_value": "mgmt_ip",
        "value": "192.168.1.10"10000",
      "data_type": "ipv4"
      }integer",
      "pending"is_pending": false,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",
        "editable": true
      }
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns the device nameparameters and variables
400	Bad Request - InvalidMissing required parent__name parameter or invalid query parameters
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified name does not foundexist

500 Internal Server Error - Server error during parameter retrieval

---

PUT /inventory_device_name_variables/{parent__name}/

UpdateDescription: deviceUpdates parameterconfiguration parameters and variables for a specific inventorydevice device.identified by name. This endpoint allows you to modify device settings, apply pending configurations, and bulk updatesupdate 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 andacross parameters.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	NameThe ofdevice name in the parentURL path identifying which device to update
data	string	body	Yes	JSON datapayload containing the parameter updates to apply to the device

ExamplecURL Request: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/jsonjson" \
  -d '{
    "parameters": [
      {
        "variable_name": "hostname",
        "value": "router-01-updated.company.01.newdomain.com"
      },
      {
        "variable_name": "ip_address"interface_speed", 
        "value": "192.168.1.15"10000"
      },
      {
        "variable_name": "description"snmp_community",
        "value": "Updated main office router"production_read_v2"
      }
    ],
    "force_commit"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:

{
  "success"status": true,
  "updated_count": 3,success",
  "device_name": "router-01",
  "parameters_updated"updated_parameters": [
    {
      "variable_name": "hostname",
      "old_value"previous_value": "router-01.staging.company.com",
      "new_value": "router-01-updated.01.production.company.com",
      "status": "updated"pending",
      "requires_restart": false
    },
    {
      "variable_name": "ip_address"interface_speed", 
      "old_value"previous_value": "192.168.1.10"1000",
      "new_value": "192.168.1.15"10000",
      "status": "updated"applied",
      "requires_restart": true
    },
    {
      "variable_name": "description"vlan_config",
      "old_value"previous_value": null,"100,200",
      "new_value": "Updated main office router"100,200,300",
      "status": "created"pending",
      "requires_restart": false
    }
  ],
  "pending_changes"summary": false{
    "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 format or parametersvalidation errors
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified name does not foundexist
422409	Unprocessable EntityConflict - ValidationParameter errorsupdate inconflicts with existing pending changes

500 Internal Server Error - Server error during parameter dataupdate

---

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 specificPagination device namesEffectively: AlwaysFor providelarge exactinventories, devicealways names inuse the parent__namelimit parameter (recommended: 50-100 items per page) and implement proper pagination handling to avoid unexpectedtimeouts resultsand excessive memory usage.

• Leverage filteringFiltering: Use specific parameter filtering optionsfilters (parameter__variable_name, parameter__name) to retrievereduce onlyresponse needed datasize and improve performance when you only need specific configuration data.

• WildcardHandle usagePending Changes: WhenAlways check the is_pending field in responses and consider using the wildcard=pending=true, bequery cautiousparameter withto broadidentify patternsdevices asrequiring theyattention maybefore returnmaking largenew resultchanges.

  sets
• Batch updates: Group multiple parameter updates in a single PUT request to maintain consistency and reduce API calls

Force updatesUpdates wiselyJudiciously: Use force_update=true onlysparingly whenas it triggers real-time device communication, which can impact performance. Reserve it for critical operations where you need the mostabsolute currentlatest data,data.

as it may impact performance

Pagination: Implement properProper pagination using limit and offset for devices with many parameters

Error handlingHandling: Always checkhandle for404 validationresponses errorswhen 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 responses,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 with specific data types

Pending changes: Monitor the pending flag to trackenable configurationquick changesrollback thatif haven'tissues beenoccur. applied to devices yet

---