Skip to main content

Inventory Device Serial Variables

The Inventory Device Serial Variables API provides access to device-specific configuration parameters and variables for devices in your inventory. These endpoints allow you to retrieve and update variable settings associated with specific device serial numbers, enabling centralized device configuration management and monitoring of pending changes.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Serial Variables API category manages configuration variables and parameters for individual devices in your inventory system. Each device, identified by its unique serial number, can have multiple configurable parameters such as network settings, operational thresholds, feature flags, and custom variables.

Key Concepts:

  • Device Serial Variables: Configuration parameters tied to specific device serial numbers
  • Variable Names: Unique identifiers for configuration parameters (e.g., "network_timeout", "max_connections")
  • Parameter Names: Human-readable names for configuration options
  • Pending Status: Indicates whether configuration changes are waiting to be applied to the device
  • Extra Information: Additional metadata or computed values related to parameters

Common Scenarios:

  • Retrieving current configuration for a specific device before maintenance
  • Bulk updating device settings across multiple parameters
  • Monitoring which devices have pending configuration changes
  • Filtering devices by specific parameter types or values
  • Implementing configuration templates and standardized settings

This API supports wildcard searching for flexible parameter queries and provides pagination for handling large numbers of device variables efficiently.

Endpoints

GET /inventory_device_serial_variables/

Description: Retrieves a list of configuration variables and parameters for devices based on serial number and optional filtering criteria. This endpoint is essential for viewing current device configurations, checking for pending changes, and filtering specific parameter types across your device inventory.

Use Cases:

  • Get all configuration variables for a specific device before performing updates
  • Monitor devices with pending configuration changes that need to be applied
  • Filter specific parameter types (e.g., network settings) across multiple devices
  • Audit current configuration states for compliance reporting

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV-2024-001&parameter__variable_name=network_timeout,max_connections&pending=true&limit=20

Parameters:

Parameter Type In Required Description
parent__serial_number string query Yes Filter by device serial number. This identifies the specific device whose variables you want to retrieve
parameter__variable_name string query No Comma-separated list of specific variable names to retrieve (e.g., "network_timeout,device_mode")
parameter__name string query No Comma-separated list of human-readable parameter names to filter by
parameter__short_name string query No Comma-separated list of parameter short names for concise identification
limit integer query No Number of results per page (default varies, typically 50-100)
offset integer query No Starting index for pagination (0-based)
pending boolean query No Filter to show only variables with pending changes (true) or applied changes (false)
wildcard boolean query No Enable wildcard (*) matching in variable_name or parameter_name fields
extra boolean query No Include additional metadata and computed values for each parameter

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV-2024-001&parameter__variable_name=network_timeout,max_connections&extra=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1001,
      "name": "Network Timeout",
      "variable_name": "network_timeout",
      "value": "30",
      "type": "integer",
      "short_name": "net_timeout",
      "extra": true,
      "extra_value": "seconds",
      "pending": false
    },
    {
      "id": 1002,
      "name": "Maximum Connections",
      "variable_name": "max_connections",
      "value": "100",
      "type": "integer",
      "short_name": "max_conn",
      "extra": false,
      "extra_value": null,
      "pending": true
    },
    {
      "id": 1003,
      "name": "Device Mode",
      "variable_name": "device_mode",
      "value": "production",
      "type": "string",
      "short_name": "mode",
      "extra": true,
      "extra_value": "enum:production,staging,development",
      "pending": false
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns the filtered device variables
400 Bad Request - Invalid query parameters or missing required serial number
401 Unauthorized - Invalid or missing Bearer token
404 Not Found - Device serial number does not exist

PUT /inventory_device_serial_variables/{parent__serial_number}/

Description: Updates configuration variables for a specific device identified by its serial number. This endpoint allows bulk updates of multiple parameters in a single request, automatically marking changes as pending until they can be synchronized with the physical device.

Use Cases:

  • Apply configuration templates to newly provisioned devices
  • Update network settings across multiple parameters simultaneously
  • Implement configuration changes as part of maintenance workflows
  • Synchronize device settings with centralized configuration policies

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV-2024-001/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes The serial number of the device to update (included in URL path)
data string body Yes JSON payload containing the variable updates to apply

Request Body Format:

{
  "variables": [
    {
      "variable_name": "network_timeout",
      "value": "45"
    },
    {
      "variable_name": "max_connections",
      "value": "150"
    }
  ]
}

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV-2024-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": [
      {
        "variable_name": "network_timeout",
        "value": "45"
      },
      {
        "variable_name": "device_mode",
        "value": "staging"
      }
    ]
  }'

Example Response:

{
  "id": 1001,
  "name": "Network Timeout",
  "variable_name": "network_timeout",
  "value": "45",
  "type": "integer",
  "short_name": "net_timeout",
  "extra": true,
  "extra_value": "seconds",
  "pending": true
}

Response Codes:

Status Description
200 Success - Variables updated successfully
400 Bad Request - Invalid data format or variable names
401 Unauthorized - Invalid or missing Bearer token
404 Not Found - Device serial number does not exist
422 Validation Error - Invalid parameter values or constraints

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all configuration variables for a specific device to verify current settings before performing maintenance or troubleshooting.

# Get all variables for device
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV-2024-001&extra=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Bulk Configuration Update

Update multiple network-related parameters for a device in preparation for a network infrastructure change.

# Update network configuration
curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV-2024-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": [{"variable_name": "network_timeout", "value": "60"}, {"variable_name": "retry_attempts", "value": "5"}]}'

Use Case 3: Pending Changes Monitoring

Identify all devices with pending configuration changes that need to be synchronized.

# Find devices with pending changes
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV-2024-001&pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Parameter Type Filtering

Retrieve only specific types of configuration parameters using wildcard matching.

# Get all network-related parameters
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV-2024-001&parameter__variable_name=network_*&wildcard=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Configuration Template Application

Apply a standardized configuration template to a newly provisioned device.

# Apply production configuration template
curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV-2024-NEW/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": [{"variable_name": "device_mode", "value": "production"}, {"variable_name": "log_level", "value": "warn"}, {"variable_name": "max_connections", "value": "200"}]}'

Best Practices

  • Always specify the device serial number: The parent__serial_number parameter is required for all GET requests and should be the exact serial number as registered in the inventory system.

  • Use pagination for large result sets: When querying devices with many variables, implement pagination using limit and offset parameters to avoid timeout issues and improve performance.

  • Handle pending status appropriately: After updating variables, they may remain in a "pending" state until synchronized with the physical device. Monitor the pending field and implement appropriate retry logic for critical updates.

  • Validate variable types and constraints: Before sending updates, ensure values match the expected type (string, integer, boolean) and any constraints indicated in the extra_value field.

  • Use wildcard filtering judiciously: Wildcard searches can be powerful but may impact performance. Use specific parameter names when possible, and enable wildcards only when necessary.

  • Implement proper error handling: Check response codes and handle validation errors (422) by reviewing the error details and correcting invalid parameter values.

  • Cache frequently accessed variables: If your application frequently reads the same device variables, implement caching strategies while respecting the pending status for real-time accuracy.

  • Batch related updates: When updating multiple related parameters, use a single PUT request rather than multiple individual requests to ensure consistency and reduce API load.

Back to top