Shared Manager Client

Every example uses the same API-key-only ManagerClient and shared command-line helpers.

Request Flow

Command module
  → shared CLI configuration
  → ManagerClient
  → GET /dataservice/client/token
  → authenticated /dataservice request

The client sends the API key as a bearer credential when it requests the XSRF token. It stores that token only in memory and sends both headers on subsequent operations:

Authorization: Bearer <API_KEY>
X-XSRF-TOKEN: <XSRF_TOKEN>

Create a Client

Most commands use the shared helper so connection options remain consistent:

from utilities.cli import client_from_args, create_parser

parser = create_parser("List an API resource.")
args = parser.parse_args()

with client_from_args(args) as client:
    payload = client.get("/client/about")

client_from_args reads vmanage, port, and apikey from .env or the process environment. The API key is deliberately not accepted as a command-line argument, which avoids exposing it in shell history and process listings.

Send API Requests

Paths are relative to /dataservice:

payload = client.get("/system/device/vedges")
payload = client.get("/device/interface", params={"deviceId": system_ip})
payload = client.post("/statistics/interface/aggregation", payload=query)
payload = client.put("/some/path", payload=request_body)
payload = client.delete("/some/path")

Use params for query parameters and payload for a JSON request body. Do not build query strings manually.

Connection and Error Handling

The shared client provides:

• TLS certificate verification by default
• A bounded timeout on every request
• JSON decoding with support for empty and plain-text responses
• HTTP and transport errors with method, path, and status context
• Context-manager cleanup for the underlying HTTP session

All command modules call the shared run() wrapper, which turns expected API and validation failures into concise terminal errors.

Protect Secrets

• Store apikey only in .env, an environment variable, or a secret manager.
• Do not print request headers or the client session.
• Do not save the XSRF token in result files.
• Prefer a CA bundle over disabling certificate validation.
• Rotate an API key immediately if it appears in terminal capture, logs, or source control.

Extend the Client

New scripts normally do not need to change ManagerClient. Import the shared helpers, create a parser, open the client with a context manager, and pass the response to utilities.tools.emit.

Continue with Python Monitoring Examples for a registry-based extension pattern.