Inventory Device Setting

The Inventory Device Setting API provides endpoints for managing configuration parameters and settings for devices within your inventory system. These endpoints allow you to retrieve, update, and modify device-specific settings such as operational parameters, configuration values, and custom properties that control device behavior and functionality.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Setting API enables you to manage configuration parameters for devices in your inventory system. Device settings are parameter-value pairs that define how individual devices should operate, including network configurations, operational thresholds, feature toggles, and custom properties.

Key Concepts:

Parent ID: References the specific device these settings belong to
Parameters: Predefined configuration options with variable names, display names, and short names
Settings: The actual values assigned to parameters for specific devices
Pending Status: Indicates whether setting changes are waiting to be applied to the device

Common Use Cases:

Configuring network settings for newly deployed devices
Updating operational parameters across multiple devices
Managing feature flags and custom properties
Bulk configuration management for device fleets
Tracking pending configuration changes before deployment

These endpoints work together to provide a complete configuration management system where you can list current settings, and update them as needed for operational requirements.

Endpoints

GET /inventory_device_setting/

Description: Retrieves a paginated list of device settings based on various filter criteria. This endpoint is essential for viewing current device configurations, finding settings by parameter names, and checking for pending changes across your device inventory.

Use Cases:

View all configuration settings for a specific device
Find devices with specific parameter configurations
Monitor pending configuration changes across your fleet
Audit device configurations for compliance

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_setting/?parent_id=123&parameter__variable_name=network_timeout&pending=false

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	query	Yes	The device ID to filter settings for. Required to specify which device's settings to retrieve
parameter_id	string	query	No	Filter by specific parameter ID
parameter__variable_name	string	query	No	Filter by parameter's variable name (e.g., "network_timeout", "max_connections")
parameter__name	string	query	No	Filter by parameter's display name
parameter__short_name	string	query	No	Filter by parameter's abbreviated name
limit	integer	query	No	Number of results per page (default: 20, max: 100)
offset	integer	query	No	Starting position for pagination
pending	boolean	query	No	Filter for settings awaiting deployment (true) or applied settings (false)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_setting/?parent_id=123&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,
  "next": "https://control.zequenze.com/api/v1/inventory_device_setting/?parent_id=123&limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "parent_id": 123,
      "parameter": {
        "id": "net_timeout",
        "variable_name": "network_timeout",
        "name": "Network Timeout",
        "short_name": "Net TO"
      },
      "value": "30",
      "pending": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:25:00Z"
    },
    {
      "id": 2,
      "parent_id": 123,
      "parameter": {
        "id": "max_conn",
        "variable_name": "max_connections",
        "name": "Maximum Connections",
        "short_name": "Max Conn"
      },
      "value": "100",
      "pending": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-22T09:15:00Z"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns the filtered device settings
400	Bad Request - Invalid query parameters or missing required parent_id
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to view device settings

PUT /inventory_device_setting/{parent_id}/

Description: Performs a complete update of device settings for the specified device. This endpoint replaces all existing settings for the device with the provided data set. Use this when you need to perform bulk configuration updates or reset a device's configuration entirely.

Use Cases:

Complete device reconfiguration during maintenance
Applying standardized configuration templates to devices
Resetting device settings to factory or baseline configurations
Bulk updates when migrating device configurations

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	path	Yes	The device ID whose settings will be completely updated
data	string	body	Yes	Complete JSON payload containing all device settings to be applied

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_setting/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [
      {
        "parameter_id": "network_timeout",
        "value": "45"
      },
      {
        "parameter_id": "max_connections",
        "value": "150"
      },
      {
        "parameter_id": "enable_logging",
        "value": "true"
      }
    ]
  }'

Example Response:

{
  "success": true,
  "message": "Device settings updated successfully",
  "updated_settings": [
    {
      "id": 1,
      "parent_id": 123,
      "parameter": {
        "id": "network_timeout",
        "variable_name": "network_timeout",
        "name": "Network Timeout"
      },
      "value": "45",
      "pending": true,
      "updated_at": "2024-01-22T15:30:00Z"
    },
    {
      "id": 2,
      "parent_id": 123,
      "parameter": {
        "id": "max_connections",
        "variable_name": "max_connections", 
        "name": "Maximum Connections"
      },
      "value": "150",
      "pending": true,
      "updated_at": "2024-01-22T15:30:00Z"
    }
  ]
}

Response Codes:

Status	Description
200	Success - All device settings updated successfully
400	Bad Request - Invalid data format or parameter values
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to modify device settings
404	Not Found - Device with specified parent_id does not exist

PATCH /inventory_device_setting/{parent_id}/

Description: Performs partial updates to specific device settings without affecting other existing settings. This endpoint allows you to modify individual parameters or small groups of settings while preserving all other current configurations. Ideal for targeted configuration changes.

Use Cases:

Updating individual configuration parameters (e.g., changing timeout values)
Fine-tuning specific device settings based on performance monitoring
Applying security patches that require configuration changes
Making incremental adjustments to operational parameters

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	path	Yes	The device ID whose settings will be partially updated
data	string	body	Yes	JSON payload containing only the specific settings to be modified

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_setting/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "parameter_id": "network_timeout",
        "value": "60"
      }
    ]
  }'

Example Response:

{
  "success": true,
  "message": "Device settings partially updated",
  "updated_settings": [
    {
      "id": 1,
      "parent_id": 123,
      "parameter": {
        "id": "network_timeout",
        "variable_name": "network_timeout",
        "name": "Network Timeout",
        "short_name": "Net TO"
      },
      "value": "60",
      "previous_value": "45",
      "pending": true,
      "updated_at": "2024-01-22T16:45:00Z"
    }
  ],
  "unchanged_settings_count": 24
}

Response Codes:

Status	Description
200	Success - Specified settings updated successfully
400	Bad Request - Invalid parameter IDs or values in update data
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to modify device settings
404	Not Found - Device or specified parameters do not exist

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all settings for multiple devices to ensure compliance with organizational standards. Use the GET endpoint with different parent_id values and compare configurations across your device fleet.

Use Case 2: Bulk Configuration Deployment

Apply standardized settings to new devices or update existing devices with new operational parameters. Use PUT for complete configuration replacement or PATCH for targeted updates.

Use Case 3: Monitoring Pending Changes

Track configuration changes that haven't been deployed to devices yet by filtering with pending=true. This helps manage deployment schedules and ensure changes are properly applied.

Use Case 4: Parameter-Based Configuration Management

Find all devices with specific parameter configurations using the parameter filter options, enabling targeted updates across devices with similar configurations.

Use Case 5: Incremental Configuration Updates

Use PATCH to make small, targeted changes to device settings without disrupting other configurations, ideal for performance tuning and gradual rollouts.

Best Practices

Always specify parent_id: The parent_id parameter is required for GET requests and critical for identifying the correct device for updates.
Use pagination effectively: For devices with many settings, implement proper pagination using limit and offset to avoid performance issues.
Monitor pending changes: Regularly check for pending settings using the pending filter to ensure configuration changes are properly deployed.
Validate parameter names: Use the parameter filter options to verify parameter names and IDs before making updates to avoid configuration errors.
Implement proper error handling: Always check response codes and handle 404 errors for non-existent devices or parameters gracefully.
Use PATCH for incremental updates: When modifying only a few settings, use PATCH instead of PUT to preserve existing configurations and reduce the risk of accidental overwrites.
Batch related changes: Group related configuration changes into single API calls when possible to maintain configuration consistency and reduce API overhead.