v1.1 Release Notes

Overview

v1.1 focuses on API maturity and production readiness. The headline changes are URL versioning, structured observability, and a suite of reliability features that make NAAS suitable for production deployments.

Migration Guide

Breaking changes

None. All v1.0 API calls continue to work unchanged.

Deprecations

device_type parameter was renamed to platform in v1.0 and remains deprecated in v1.1. It will be removed in v2.0. Update your requests if you haven't already:

// Before (still works, but deprecated)
{ "host": "192.168.1.1", "device_type": "cisco_ios", "commands": ["show version"] }

// After
{ "host": "192.168.1.1", "platform": "cisco_ios", "commands": ["show version"] }

Response shape changes

GET /healthcheck — the response shape has changed significantly:

// v1.0
{ "status": "OK", "app": "naas", "version": "1.0.0" }

// v1.1
{
  "status": "healthy",
  "version": "1.1.0",
  "uptime_seconds": 3600,
  "components": {
    "redis": { "status": "healthy" },
    "queue": { "status": "healthy", "depth": 0 }
  }
}

status is now "healthy" or "degraded" (not "OK"). The app field is removed. components is added.

GET /v1/send_command/{job_id} with status: failed — now includes an error field with the failure reason. Previously it was always null.

New error codes

Validation errors now return 422 (Unprocessable Entity) instead of 400, with a structured errors array:

{
  "validation_error": {
    "json": [
      { "loc": ["ip"], "msg": "value is not a valid IPv4 address", "type": "value_error" }
    ]
  }
}

What's New

API versioning

All endpoints are now available under /v1/:

POST /v1/send_command
POST /v1/send_config
GET /v1/send_command/{job_id}
GET /v1/send_config/{job_id}
GET /v1/jobs
GET /v1/healthcheck

The legacy unversioned routes (/send_command, /send_config) remain functional but return deprecation headers:

X-API-Deprecated: true
X-API-Sunset: 2027-01-01
X-API-Version: v1

All responses now include X-API-Version: v1.

Interactive API documentation

Swagger UI is available at /apidoc. The OpenAPI spec is at /apidoc/openapi.json. Basic Auth is wired into the "Try it out" button.

Job history endpoint

GET /v1/jobs lists jobs with pagination and status filtering:

# All jobs, page 1
curl -k -u "user:pass" https://localhost:8443/v1/jobs

# Failed jobs only
curl -k -u "user:pass" "https://localhost:8443/v1/jobs?status=failed"

# Paginate
curl -k -u "user:pass" "https://localhost:8443/v1/jobs?page=2&per_page=50"

Structured JSON logging

All log output is now JSON. Each line includes timestamp, level, logger, and message fields, making logs parseable by ELK, Splunk, CloudWatch, and similar tools.

Configure log level via LOG_LEVEL environment variable (default: INFO; DEBUG in dev).

Correlation ID tracing

Every API request is assigned a request_id (UUID), returned as X-Request-ID in the response. This ID is also the RQ job ID, and it flows through all worker log lines — enabling end-to-end tracing of a request across API and worker logs.

Supply your own ID for external correlation:

curl -k -X POST https://localhost:8443/v1/send_command \
  -H "X-Request-ID: my-trace-id-1234" \
  ...

Enhanced health check

GET /healthcheck now performs a live Redis ping and reports component status. Returns status: degraded when Redis is unreachable, enabling health-check-based load balancer routing.

Circuit breaker

Repeated connection failures to a device automatically open a circuit breaker, fast-failing subsequent requests to that device for a configurable timeout period. This prevents a single unreachable device from exhausting the worker pool.

Environment variable	Default	Description
`CIRCUIT_BREAKER_THRESHOLD`	`5`	Failures before circuit opens
`CIRCUIT_BREAKER_TIMEOUT`	`300`	Seconds before circuit attempts recovery

When the circuit is open, jobs return immediately with an error rather than timing out.

Device lockout

If 10 connection failures to the same device IP occur within 10 minutes (across any user), all access to that device is blocked for 10 minutes. This prevents credential-spray abuse. Blocked requests return 403 Forbidden.

Graceful shutdown

Workers now handle SIGTERM gracefully — finishing any in-flight job before exiting. This prevents job loss during container restarts and deployments.

Environment variable	Default	Description
`SHUTDOWN_TIMEOUT`	`60`	Seconds to wait for in-flight job before force-exit

Configurable job TTLs

Job results are retained in Redis for a configurable period:

Environment variable	Default	Description
`JOB_TTL_SUCCESS`	`86400` (24h)	Retention for successful job results
`JOB_TTL_FAILED`	`604800` (7 days)	Retention for failed job results

Upgrade Steps

Pull the latest image or update your deployment
Update any healthcheck monitors that check for status: "OK" — it is now "healthy"
Update any clients that use device_type to use platform instead (not required, but recommended before v2.0)
Review error handling — validation errors are now 422, not 400
Optionally set JOB_TTL_SUCCESS, JOB_TTL_FAILED, CIRCUIT_BREAKER_THRESHOLD, CIRCUIT_BREAKER_TIMEOUT, and SHUTDOWN_TIMEOUT to suit your environment