Service API User Guide

Overview

This comprehensive guide explains how the Service API supports operational processes for CPE device management. The API provides a robust set of methods for configuring, monitoring, and troubleshooting TR-069 compliant devices through the ACS (Auto Configuration Server).

Service Categories

The Service API offers the following major categories of functionality:

Common Parameters

Most API methods share several common parameters:

  • SN – Serial number of the CPE device

  • timeout – Custom operation timeout in seconds (defaults to TransactionTimeout if not specified)

  • fromCPE – Boolean flag indicating whether to get data from the device (true) or ACS database (false)

  • reprovision – Controls whether settings persist through device reboots:

    • 0 = don’t add/update provision manager data

    • 1 = add/update provision manager data

    • 2 = secondary provision (for bootstrap events without immediate task creation)

Status Codes

All API methods return consistent response codes:

  • 100 – Success

  • 201 – No device found

  • 202 – Database error

  • 203 – Incorrect request structure or non-writable parameter

  • 204 – General error

  • 205 – ACS connection error

External Configuration

The system’s behavior can be customized through several configuration files:

  • Email Server Configuration – SMTP settings for email notifications

  • Speed Test Configuration – URLs and file sizes for performance testing

  • Subscription Configuration – Parameter values for service activation/deactivation

  • Service Group Configuration – Parameter groupings for service customization

  • Wireless Configuration – Device-specific wireless parameter settings

Best Practices

  1. Check Device Status – Use the initialization method before making changes to ensure current parameter values.

  2. Timeout Management – Specify appropriate timeouts for operations, especially for slow-responding devices.

  3. Reprovision Strategy – Consider whether settings should persist through reboots or apply only once.

  4. Error Handling – Always check response codes and implement appropriate error handling.

  5. Device Compatibility – Be aware of parameter path differences between TR-098 and TR-181 devices.

Implementation Workflow

A typical implementation workflow includes:

  1. Authentication – Log in to obtain access to the API

  2. Device Identification – Locate the target device by serial number or MAC address

  3. Current State Assessment – Retrieve existing configurations

  4. Configuration Updates – Apply necessary changes to the device

  5. Verification – Confirm changes were applied successfully

  6. Monitoring – Set up appropriate provisioning for ongoing management