Inventory Device Serial Setting

The Device Serial Setting API endpoints provide access to configuration parameters and settings for specific devices in your inventory. These endpoints allow you to retrieve, update, and modify device-specific settings using the device's serial number as the primary identifier. Common use cases include reading current device configurations, updating device parameters, and managing device-specific operational settings.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Device Serial Setting API category manages configuration parameters and operational settings for individual devices in your inventory system. Each device is uniquely identified by its serial number and can have multiple configurable parameters that control various aspects of device behavior and operation.

Key Concepts:

Device Settings: Configuration parameters that define how a device operates
Parameter Variables: Named configuration options with specific data types and validation rules
Pending Settings: Configuration changes that have been submitted but not yet applied to the device
Serial Number Identification: Primary method for targeting specific devices in your inventory

Common Use Cases:

Retrieving current configuration for a specific device
Updating device operational parameters
Checking for pending configuration changes
Bulk configuration management across device fleets
Monitoring device parameter status and compliance

These endpoints work together to provide complete CRUD operations for device settings, with the GET endpoint for reading configurations and PUT/PATCH endpoints for updating them. The API supports filtering by various parameter attributes to help you find specific settings quickly.

Endpoints

GET /inventory_device_serial_setting/

Description: Retrieves a list of configuration settings for devices based on their serial number. This endpoint allows you to query device settings with various filters to find specific parameters or check for pending configuration changes. It's essential for monitoring device configurations and ensuring devices are properly configured.

Use Cases:

Retrieve all settings for a specific device by serial number
Check if a device has pending configuration changes
Find specific parameters by name or variable name
Monitor device configuration compliance across your fleet

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/?parent__serial_number=DEV001234&pending=true&limit=50

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	query	Yes	The serial number of the parent device whose settings you want to retrieve
parameter_id	string	query	No	Filter by specific parameter ID
parameter__variable_name	string	query	No	Filter settings by the parameter's variable name (e.g., "network_timeout")
parameter__name	string	query	No	Filter settings by the parameter's display name (e.g., "Network Timeout")
parameter__short_name	string	query	No	Filter settings by the parameter's short name abbreviation
limit	integer	query	No	Number of results to return per page (default pagination limit applies)
offset	integer	query	No	The starting index for paginated results
pending	boolean	query	No	When true, returns only settings with pending changes; when false, returns applied settings

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_setting/?parent__serial_number=DEV001234&parameter__variable_name=network_timeout" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 101,
      "parent_device_serial": "DEV001234",
      "parameter": {
        "id": "net_timeout",
        "variable_name": "network_timeout",
        "name": "Network Timeout",
        "short_name": "NetTO",
        "data_type": "integer",
        "unit": "seconds"
      },
      "current_value": "30",
      "pending_value": "45",
      "is_pending": true,
      "last_modified": "2024-01-15T14:30:00Z",
      "applied_at": "2024-01-15T10:15:00Z"
    },
    {
      "id": 102,
      "parent_device_serial": "DEV001234",
      "parameter": {
        "id": "auto_backup",
        "variable_name": "automatic_backup",
        "name": "Automatic Backup",
        "short_name": "AutoBak",
        "data_type": "boolean"
      },
      "current_value": "true",
      "pending_value": null,
      "is_pending": false,
      "last_modified": "2024-01-14T09:20:00Z",
      "applied_at": "2024-01-14T09:20:00Z"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns the device settings data
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_setting/{parent__serial_number}/

Description: Performs a complete update of device settings for the specified device serial number. This endpoint replaces all existing settings with the provided configuration data. Use this method when you need to set multiple parameters at once or perform a complete configuration overwrite.

Use Cases:

Apply a complete configuration template to a device
Reset device to a known good configuration state
Bulk update multiple settings simultaneously
Restore device configuration from backup

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/DEV001234/

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	path	Yes	The serial number of the device to update (specified in the URL path)
data	string	body	Yes	JSON string containing the complete settings configuration data

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_setting/DEV001234/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [
      {
        "parameter_id": "network_timeout",
        "value": "60"
      },
      {
        "parameter_id": "automatic_backup",
        "value": "true"
      },
      {
        "parameter_id": "log_level",
        "value": "info"
      }
    ]
  }'

Example Response:

{
  "device_serial": "DEV001234",
  "updated_settings": [
    {
      "parameter_id": "network_timeout",
      "parameter_name": "Network Timeout",
      "old_value": "30",
      "new_value": "60",
      "status": "pending"
    },
    {
      "parameter_id": "automatic_backup",
      "parameter_name": "Automatic Backup",
      "old_value": "true",
      "new_value": "true",
      "status": "unchanged"
    },
    {
      "parameter_id": "log_level",
      "parameter_name": "Logging Level",
      "old_value": "debug",
      "new_value": "info",
      "status": "pending"
    }
  ],
  "pending_changes": 2,
  "updated_at": "2024-01-15T15:45:00Z"
}

Response Codes:

Status	Description
200	Success - Settings updated successfully
400	Bad Request - Invalid JSON data or parameter validation failed
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device with specified serial number not found
422	Unprocessable Entity - Valid JSON but invalid parameter values

PATCH /inventory_device_serial_setting/{parent__serial_number}/

Description: Performs a partial update of device settings for the specified device serial number. This endpoint allows you to update specific settings without affecting other existing configurations. Use this method when you only need to modify a few specific parameters while leaving the rest unchanged.

Use Cases:

Update a single device parameter
Modify specific settings without affecting others
Apply incremental configuration changes
Fine-tune individual device parameters

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/DEV001234/

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	path	Yes	The serial number of the device to update (specified in the URL path)
data	string	body	Yes	JSON string containing only the specific settings to update

cURL Example:

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

Example Response:

{
  "device_serial": "DEV001234",
  "updated_settings": [
    {
      "parameter_id": "network_timeout",
      "parameter_name": "Network Timeout",
      "old_value": "30",
      "new_value": "45",
      "status": "pending",
      "change_reason": "Performance optimization"
    }
  ],
  "pending_changes": 1,
  "total_settings": 15,
  "updated_at": "2024-01-15T16:20:00Z"
}

Response Codes:

Status	Description
200	Success - Specific settings updated successfully
400	Bad Request - Invalid JSON data or parameter validation failed
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Device or specified parameter not found
422	Unprocessable Entity - Valid JSON but invalid parameter values

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all current settings for a device to perform a configuration audit or compliance check. Use the GET endpoint with the device serial number to get a complete overview of all parameters and their current values.

Use Case 2: Checking for Pending Changes

Monitor devices that have configuration changes waiting to be applied by using the GET endpoint with pending=true parameter. This helps track deployment status and ensure changes are properly applied.

Use Case 3: Single Parameter Update

When you need to adjust just one setting (like increasing a timeout value), use the PATCH endpoint to modify only that specific parameter without affecting other configurations.

Use Case 4: Configuration Template Deployment

Deploy a standard configuration template to new devices using the PUT endpoint to set all parameters at once, ensuring consistent device setup across your fleet.

Use Case 5: Parameter Search and Filtering

Find specific types of settings across devices by using parameter name filters, helping you identify devices with particular configuration patterns or locate specific parameters quickly.

Best Practices

Use Serial Numbers Correctly: Always verify device serial numbers before making updates, as incorrect serial numbers will result in 404 errors or unintended device modifications.
Handle Pending Changes: Check for pending changes before applying new settings. Consider the impact of overwriting pending configurations that haven't been applied yet.
Implement Proper Error Handling: Always check response status codes and handle validation errors appropriately. Parameter validation failures (422 status) should be clearly communicated to users.
Use Appropriate HTTP Methods: Use PATCH for single parameter updates and PUT for complete configuration replacements to follow REST best practices and avoid unintended side effects.
Implement Pagination: For devices with many settings, use the limit and offset parameters to implement proper pagination and avoid performance issues with large result sets.
Monitor Configuration Changes: Regularly audit device configurations and track pending changes to ensure your device fleet maintains proper operational parameters and security compliance.