Inventory Device Name Setting

The Inventory Device Name Setting API endpoints manage configuration parameters for specific devices in your inventory. These endpoints allow you to retrieve, modify, and update device-specific settings by device name, making it easy to configure individual devices without needing to know their internal IDs.

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 Setting API provides a streamlined way to manage configuration parameters for devices in your inventory system. Unlike traditional device management that requires internal device IDs, these endpoints use human-readable device names, making them particularly useful for automation scripts, configuration management tools, and administrative interfaces.

Key Concepts:

Device Settings: Configuration parameters that control device behavior, appearance, and functionality
Parameters: Template definitions that define what settings are available (name, type, validation rules)
Values: The actual configuration values assigned to each parameter for a specific device
Pending Status: Indicates whether setting changes are waiting to be applied to the physical device

Common Integration Scenarios:

Bulk device configuration during deployment
Automated configuration updates based on device roles or locations
Configuration backup and restore operations
Compliance monitoring and remediation
Integration with external configuration management systems

The API supports both complete updates (PUT) and partial modifications (PATCH), with built-in change tracking and pending status monitoring to ensure configuration changes are properly synchronized with physical devices.

Endpoints

GET /inventory_device_name_setting/

Description: Retrieves a paginated list of configuration settings for devices, filtered by device name and optionally by parameter characteristics. This endpoint is essential for auditing device configurations, bulk operations, and synchronization processes.

Use Cases:

Audit all configuration settings for a specific device
Export device configurations for backup or compliance reporting
Sync configurations between environments
Monitor pending configuration changes across devices
Filter settings by parameter types for bulk operations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/?parent__name=router-main-office&parameter__name=hostname&limit=50

Parameters:

Parameter	Type	In	Required	Description
parent__name	string	query	Yes	The name of the device to retrieve settings for
parameter_id	string	query	No	Filter by specific parameter ID
parameter__variable_name	string	query	No	Filter settings by parameter variable name (e.g., 'wifi_ssid', 'admin_password')
parameter__name	string	query	No	Filter settings by human-readable parameter name
parameter__short_name	string	query	No	Filter settings by parameter short name/slug
limit	integer	query	No	Number of results per page (default: 20)
offset	integer	query	No	Starting index for pagination (default: 0)
pending	boolean	query	No	Filter to show only pending or applied settings

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_setting/?parent__name=router-branch-001&parameter__variable_name=wifi_enabled&limit=25" \
  -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_setting/?limit=25&offset=25&parent__name=router-branch-001",
  "previous": null,
  "results": [
    {
      "id": 12847,
      "parent_id": "dev_001",
      "parent__name": "router-branch-001",
      "parameter": {
        "id": 45,
        "name": "WiFi Network Enabled",
        "short_name": "wifi-enabled",
        "variable_name": "wifi_enabled",
        "type": "boolean",
        "position": 10,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 5,
          "name": "Wireless Configuration",
          "service": "networking",
          "discovery_group": "wireless",
          "title": "WiFi Settings"
        }
      },
      "value": "true",
      "created": "2024-01-15T09:30:00Z",
      "last_change": "2024-01-20T14:22:00Z",
      "pending": false
    },
    {
      "id": 12848,
      "parent_id": "dev_001",
      "parent__name": "router-branch-001",
      "parameter": {
        "id": 46,
        "name": "Network SSID",
        "short_name": "ssid",
        "variable_name": "wifi_ssid",
        "type": "string",
        "position": 15,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 5,
          "name": "Wireless Configuration",
          "service": "networking",
          "discovery_group": "wireless",
          "title": "WiFi Settings"
        }
      },
      "value": "BranchOffice-WiFi",
      "created": "2024-01-15T09:30:00Z",
      "last_change": "2024-01-18T11:45:00Z",
      "pending": true
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns paginated list of device settings
400	Bad Request - Missing required parent__name parameter
401	Unauthorized - Invalid or missing API token
404	Not Found - Device with specified name does not exist

PUT /inventory_device_name_setting/{parent__name}/

Description: Performs a complete update of device settings, replacing all configurable parameters with the provided values. This endpoint is ideal for full configuration deployments, device provisioning, and configuration restoration scenarios.

Use Cases:

Deploy complete device configurations during initial setup
Restore device configurations from backup
Standardize configurations across device groups
Reset device configurations to known-good states
Migrate configurations between devices

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/

Parameters:

Parameter	Type	In	Required	Description
parent__name	string	path	Yes	The name of the device to update settings for
data	object	body	Yes	Complete device configuration object containing all parameter values

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wifi_enabled": "true",
    "wifi_ssid": "BranchOffice-Secure",
    "admin_timeout": "1800",
    "backup_enabled": "true",
    "log_level": "info"
  }'

Example Response:

{
  "id": 12847,
  "parent_id": "dev_001",
  "parent__name": "router-branch-001",
  "parameter": {
    "id": 45,
    "name": "WiFi Network Enabled",
    "short_name": "wifi-enabled",
    "variable_name": "wifi_enabled",
    "type": "boolean",
    "position": 10,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 5,
      "name": "Wireless Configuration",
      "service": "networking",
      "discovery_group": "wireless",
      "title": "WiFi Settings"
    }
  },
  "value": "true",
  "created": "2024-01-15T09:30:00Z",
  "last_change": "2024-01-22T16:30:00Z",
  "pending": true
}

Response Codes:

Status	Description
200	Success - Configuration updated successfully
400	Bad Request - Invalid configuration data or validation errors
401	Unauthorized - Invalid or missing API token
404	Not Found - Device with specified name does not exist
422	Unprocessable Entity - Configuration violates device constraints

PATCH /inventory_device_name_setting/{parent__name}/

Description: Performs a partial update of device settings, modifying only the specified parameters while leaving others unchanged. This endpoint is perfect for targeted configuration changes, incremental updates, and automated configuration adjustments.

Use Cases:

Update specific settings without affecting others
Apply configuration changes from monitoring systems
Implement gradual configuration rollouts
Fix specific configuration issues
Update device settings based on external triggers

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/

Parameters:

Parameter	Type	In	Required	Description
parent__name	string	path	Yes	The name of the device to partially update settings for
data	object	body	Yes	Partial configuration object containing only the parameters to update

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wifi_ssid": "NewBranchOffice-WiFi",
    "log_level": "debug"
  }'

Example Response:

{
  "id": 12848,
  "parent_id": "dev_001",
  "parent__name": "router-branch-001",
  "parameter": {
    "id": 46,
    "name": "Network SSID",
    "short_name": "ssid",
    "variable_name": "wifi_ssid",
    "type": "string",
    "position": 15,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 5,
      "name": "Wireless Configuration",
      "service": "networking",
      "discovery_group": "wireless",
      "title": "WiFi Settings"
    }
  },
  "value": "NewBranchOffice-WiFi",
  "created": "2024-01-15T09:30:00Z",
  "last_change": "2024-01-22T17:15:00Z",
  "pending": true
}

Response Codes:

Status	Description
200	Success - Settings updated successfully
400	Bad Request - Invalid parameter names or values
401	Unauthorized - Invalid or missing API 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

Retrieve all configuration settings for a device to perform compliance checking or generate configuration reports. Use the GET endpoint with filtering to focus on specific parameter groups.

Use Case 2: Bulk Configuration Deployment

Deploy standardized configurations across multiple devices using the PUT endpoint in a loop, ensuring all devices in a location or role have identical baseline settings.

Use Case 3: Automated Configuration Updates

Monitor device metrics and automatically adjust configuration parameters using the PATCH endpoint when thresholds are exceeded or conditions change.

Use Case 4: Configuration Backup and Restore

Export complete device configurations using the GET endpoint for backup, then restore them using PUT during disaster recovery or device replacement scenarios.

Use Case 5: Gradual Setting Updates

Implement phased configuration rollouts by using PATCH to update specific settings across device groups, monitoring the pending status to ensure changes are applied successfully.

Best Practices

Use Descriptive Device Names: Since these endpoints rely on device names, ensure your naming convention is consistent and meaningful for easier automation and maintenance.
Monitor Pending Status: Always check the pending field in responses to understand when configuration changes are waiting to be applied to physical devices. Use the pending parameter to filter and monitor deployment status.
Implement Proper Error Handling: Device configuration changes can fail due to hardware constraints, network issues, or validation rules. Implement retry logic and proper error handling for production systems.
Leverage Parameter Filtering: Use parameter filtering (by name, variable_name, or type) to focus on specific configuration areas, improving performance and reducing complexity in large-scale deployments.
Batch Related Changes: When updating multiple related settings, use PATCH with multiple parameters in a single request rather than making individual calls to maintain configuration consistency and reduce API overhead.
Validate Configuration Data: Always validate parameter types and values against the parameter definitions before making update requests to avoid unnecessary API errors and deployment failures.