Skip to main content

Inventory Device Whip

The Inventory Device WHIP endpoints provide remote device management capabilities, allowing you to execute critical operations on network devices through the WHIP (Web-based Hardware Interface Protocol). These endpoints enable administrators to perform essential maintenance tasks like reboots, factory resets, and configuration synchronization remotely.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device WHIP API category is designed for remote device management operations within your network infrastructure. This API allows network administrators and automated systems to perform critical maintenance operations on managed devices without requiring physical access.

The WHIP (Web-based Hardware Interface Protocol) integration enables you to execute various device operations remotely, including system reboots, factory resets, configuration synchronization, and device reconfiguration. This is particularly valuable for managing distributed network infrastructure, IoT devices, or equipment in remote locations where physical access is limited or costly.

Key Operations Available:

  • Reboot: Perform a soft restart of the device
  • Factory Reset: Reset device to factory defaults (preserves network connectivity)
  • Device Factory Reset: Complete factory reset including network settings
  • Configuration Sync: Synchronize device configuration with the central management system
  • Device Reconfigure: Apply new configuration parameters to the device

This API is commonly used in network operations centers (NOCs), automated maintenance workflows, and device lifecycle management systems.

Endpoints

GET /inventory_device_whip/{id}/

Description: Retrieves the current WHIP operation status or initiates a device operation for a specific inventory device. This endpoint serves as both a status checker and operation trigger, depending on how it's called. The operation parameter determines which remote action will be performed on the target device.

Use Cases:

  • Remotely reboot unresponsive network devices
  • Perform scheduled factory resets during maintenance windows
  • Synchronize device configurations after policy updates
  • Reconfigure devices with new network parameters
  • Check the status of ongoing device operations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_whip/12345/?operation=reboot

Parameters:

Parameter Type In Required Description
id integer path Yes The unique identifier of the inventory device to perform the operation on
operation string query No The operation to perform on the device. When provided, triggers the specified action

Operation Values:

Value Description
reboot Performs a soft reboot of the device while preserving all configurations
factory Resets device to factory defaults but maintains network connectivity settings
device_factory Complete factory reset including all network and configuration settings
sync Synchronizes the device configuration with the central management system
reconf Applies new configuration parameters and reconfigures the device

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_whip/12345/?operation=reboot" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 12345,
  "operation": "reboot",
  "status": "initiated",
  "device_info": {
    "device_id": 12345,
    "device_name": "switch-floor-2-east",
    "device_type": "network_switch",
    "serial_number": "SW2E-8845-XXYY",
    "ip_address": "192.168.2.45",
    "location": "Building A - Floor 2 East"
  },
  "operation_details": {
    "initiated_at": "2024-01-15T14:30:00Z",
    "estimated_completion": "2024-01-15T14:32:00Z",
    "operation_id": "op_67890abcdef"
  }
}

Status Check Example (without operation parameter):

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_whip/12345/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Status Response Example:

{
  "id": 12345,
  "operation": "reboot",
  "status": "completed",
  "last_operation": {
    "operation_type": "reboot",
    "initiated_at": "2024-01-15T14:30:00Z",
    "completed_at": "2024-01-15T14:31:45Z",
    "result": "success",
    "operation_id": "op_67890abcdef"
  },
  "device_info": {
    "device_id": 12345,
    "device_name": "switch-floor-2-east",
    "online_status": "online",
    "last_seen": "2024-01-15T14:32:15Z"
  }
}

Response Codes:

Status Description
200 Success - Operation initiated or status retrieved successfully
400 Bad Request - Invalid operation parameter or malformed request
401 Unauthorized - Invalid or missing API token
404 Not Found - Device ID does not exist or is not accessible
409 Conflict - Another operation is currently in progress on this device
503 Service Unavailable - Device is offline or unreachable

Common Use Cases

Use Case 1: Automated Network Maintenance

Schedule periodic reboots of network devices during maintenance windows to prevent memory leaks and ensure optimal performance. Use the reboot operation integrated with your maintenance scheduling system.

Use Case 2: Configuration Drift Remediation

When monitoring systems detect configuration drift, use the sync operation to restore devices to their intended configuration state without manual intervention.

Use Case 3: Device Deployment and Provisioning

During device replacement or new deployments, use device_factory followed by reconf to ensure devices start with a clean state and receive the correct configuration for their location and role.

Use Case 4: Emergency Recovery Operations

When devices become unresponsive or misconfigured, use the appropriate factory reset operation (factory or device_factory) based on whether network connectivity needs to be preserved for remote recovery.

Use Case 5: Bulk Configuration Updates

After updating network policies or security settings, use the reconf operation across multiple devices to ensure consistent policy enforcement throughout your infrastructure.

Best Practices

  • Operation Sequencing: Wait for completion of one operation before initiating another on the same device. Check operation status using the endpoint without parameters.

  • Error Handling: Implement retry logic with exponential backoff for operations that fail due to temporary network issues. Monitor for 409 status codes indicating conflicting operations.

  • Maintenance Windows: Schedule disruptive operations (factory resets, reboots) during planned maintenance windows to minimize service impact.

  • Monitoring Integration: Integrate WHIP operations with your network monitoring system to track device recovery after operations and detect any issues.

  • Documentation: Always log WHIP operations with timestamps and reasons for audit trails and troubleshooting purposes.

  • Timeout Handling: Set appropriate timeouts for operations. Reboots typically complete in 2-3 minutes, while factory resets may take 5-10 minutes depending on the device type.

  • Batch Operations: When performing the same operation on multiple devices, implement parallel execution with reasonable concurrency limits to avoid overwhelming the management infrastructure.

Back to top