Inventory Device Serial Variables

The Inventory Device Serial Variables API provides endpoints for managing and retrieving configuration parameters and variables associated with specific devices in your inventory. These endpoints allow you to query device-specific settings by serial number and update device configurations 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 Serial Variables API is designed for managing device-specific configuration parameters and variables in your network inventory system. This API category focuses on device-level settings that are tied to specific serial numbers, allowing for granular control over individual device configurations.

Key Concepts:

Device Serial Variables: Configuration parameters and settings associated with specific device serial numbers
Parameter Filtering: Advanced filtering capabilities to retrieve specific configuration variables by name, short name, or variable name
Pending Settings: Track and manage configuration changes that are pending deployment to devices
Wildcard Support: Use pattern matching to query multiple related parameters efficiently

Common Use Cases:

Retrieving current configuration settings for a specific device
Bulk updating device parameters across multiple variables
Monitoring pending configuration changes before deployment
Auditing device-specific settings for compliance purposes
Automating device configuration management workflows

The API supports both read and write operations, enabling comprehensive device configuration management through programmatic interfaces.

Endpoints

GET /inventory_device_serial_variables/

Description: Retrieves configuration variables and parameters for devices based on serial number filtering. This endpoint is essential for querying current device settings, monitoring configuration states, and retrieving specific parameter values for inventory management.

Use Cases:

Audit all configuration parameters for a specific device
Retrieve pending configuration changes before deployment
Query specific parameter values across multiple devices
Monitor device settings for compliance verification

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&parameter__variable_name=hostname,ip_address&limit=50

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	query	Yes	Filter settings by the parent device's serial number. This is the primary identifier for targeting specific devices.
parameter__variable_name	string	query	No	Comma-separated list of parameter variable names to retrieve (e.g., "hostname,ip_address,vlan_id")
parameter__name	string	query	No	Comma-separated list of parameter display names to retrieve (e.g., "Device Hostname,IP Address")
parameter__short_name	string	query	No	Comma-separated list of parameter short names for abbreviated parameter identification
limit	integer	query	No	Number of results to return per page (default: 20, max: 100)
offset	integer	query	No	Starting index for pagination (default: 0)
pending	boolean	query	No	Set to true to show only parameters with pending changes awaiting deployment
wildcard	boolean	query	No	Enable wildcard (*) pattern matching in variable_name or parameter_name fields
extra	boolean	query	No	Include additional metadata and extended parameter information in the response

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&parameter__variable_name=hostname,ip_address&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_serial_variables/?limit=10&offset=10&parent__serial_number=SN123456789",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_serial_number": "SN123456789",
      "parameter": {
        "variable_name": "hostname",
        "name": "Device Hostname",
        "short_name": "host",
        "data_type": "string",
        "category": "network"
      },
      "current_value": "switch-floor-2-rack-1",
      "pending_value": "switch-floor-2-rack-1-updated",
      "is_pending": true,
      "last_modified": "2024-01-15T14:30:00Z",
      "modified_by": "admin@company.com"
    },
    {
      "id": 1002,
      "parent_serial_number": "SN123456789",
      "parameter": {
        "variable_name": "ip_address",
        "name": "Management IP Address",
        "short_name": "mgmt_ip",
        "data_type": "ipv4",
        "category": "network"
      },
      "current_value": "192.168.1.100",
      "pending_value": null,
      "is_pending": false,
      "last_modified": "2024-01-10T09:15:00Z",
      "modified_by": "network@company.com"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns device variables and parameters
400	Bad Request - Missing required parent__serial_number parameter
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified serial number not found

PUT /inventory_device_serial_variables/{parent__serial_number}/

Description: Updates configuration variables and parameters for a specific device identified by its serial number. This endpoint allows bulk updating of multiple device parameters in a single request, making it efficient for configuration management and deployment workflows.

Use Cases:

Deploy pending configuration changes to a device
Bulk update multiple device parameters simultaneously
Apply standardized configuration templates to devices
Rollback device configurations to previous states

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/SN123456789/

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	path	Yes	Serial number of the device to update (included in the URL path)
data	string	body	Yes	JSON payload containing the parameter updates and configuration changes

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [
      {
        "variable_name": "hostname",
        "value": "switch-floor-2-rack-1-new"
      },
      {
        "variable_name": "ip_address", 
        "value": "192.168.1.101"
      },
      {
        "variable_name": "vlan_id",
        "value": "100"
      }
    ],
    "deploy_immediately": false,
    "notes": "Monthly configuration update batch"
  }'

Example Request Body:

{
  "parameters": [
    {
      "variable_name": "hostname",
      "value": "switch-floor-2-rack-1-new",
      "validate": true
    },
    {
      "variable_name": "ip_address", 
      "value": "192.168.1.101",
      "validate": true
    },
    {
      "variable_name": "snmp_community",
      "value": "new_community_string",
      "validate": false
    }
  ],
  "deploy_immediately": false,
  "backup_current": true,
  "notes": "Monthly configuration update - Network segment reorganization"
}

Example Response:

{
  "success": true,
  "updated_parameters": 3,
  "device_serial_number": "SN123456789",
  "changes": [
    {
      "variable_name": "hostname",
      "previous_value": "switch-floor-2-rack-1",
      "new_value": "switch-floor-2-rack-1-new",
      "status": "pending"
    },
    {
      "variable_name": "ip_address",
      "previous_value": "192.168.1.100",
      "new_value": "192.168.1.101", 
      "status": "pending"
    },
    {
      "variable_name": "snmp_community",
      "previous_value": "[hidden]",
      "new_value": "[hidden]",
      "status": "pending"
    }
  ],
  "deployment_status": "pending",
  "backup_created": true,
  "backup_id": "backup_20240115_143000",
  "timestamp": "2024-01-15T14:30:00Z",
  "modified_by": "api_user@company.com"
}

Response Codes:

Status	Description
200	Success - Parameters updated successfully
400	Bad Request - Invalid parameter values or malformed request
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified serial number not found
422	Unprocessable Entity - Validation errors in parameter values

Common Use Cases

Use Case 1: Device Configuration Audit

Query all configuration parameters for a specific device to perform compliance auditing and verify current settings against organizational standards.

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&extra=true

Use Case 2: Network Parameter Updates

Update critical network parameters (hostname, IP address, VLAN) for a device during network reorganization or maintenance windows.

Use Case 3: Pending Changes Review

Monitor devices with pending configuration changes before deploying updates to production environments.

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&pending=true

Use Case 4: Bulk Parameter Retrieval

Retrieve specific configuration parameters across multiple API calls for reporting and monitoring dashboards.

Use Case 5: Configuration Template Deployment

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

Best Practices

Pagination: Use limit and offset parameters for large result sets to improve performance and reduce response times
Parameter Filtering: Leverage parameter filtering (variable_name, name, short_name) to retrieve only the data you need, reducing bandwidth usage
Pending Changes: Always check for pending changes before making updates to avoid conflicts or overwriting uncommitted configurations
Validation: Use the validation flags in PUT requests to catch configuration errors before deployment
Backup Strategy: Enable backup_current when making significant configuration changes to allow for quick rollbacks
Error Handling: Implement proper error handling for 422 validation errors, especially when updating critical network parameters
Rate Limiting: Space out API calls appropriately when processing multiple devices to avoid hitting rate limits
Security: Never log sensitive parameter values (passwords, SNMP communities) in your application logs
Wildcard Usage: Use wildcards sparingly and with specific patterns to avoid retrieving excessive amounts of data