Skip to content

frequently asked questions

Most Loved Features

Session Maintenance: Automatically handles session management for you. Including token refresh and session persistence.
Error Handling: Comprehensive error handling with clear exceptions for common issues.
Environment Variables: Configure clients using environment variables for sensitive data.
Rate Limit Handling: Built-in support for rate limiting and retry logic. No more HTTP 429 errors!
Authentication: Simplified authentication process with support for multiple methods.
Path Building: Easy-to-use path building for API endpoints.
Fully Typed: Type hints for better development experience.
Concurrency: Supports asynchronous operations for better performance.
Pagination: Automatically handles pagination for large datasets.
Headers: You never have to worry about headers - they are automatically set for you.
Logging: Configurable, flexible and very detailed - for debugging and monitoring.

Common Questions

How do I configure authentication?

Each client requires credentials (base_url, username, password, or token). You can provide these as arguments or set the appropriate environment variables:

  • APIC: WINGPY_APIC_BASE_URL, WINGPY_APIC_USERNAME, WINGPY_APIC_PASSWORD
  • Catalyst Center: WINGPY_CATALYST_CENTER_BASE_URL, WINGPY_CATALYST_CENTER_USERNAME, WINGPY_CATALYST_CENTER_PASSWORD
  • FMC: WINGPY_FMC_BASE_URL, WINGPY_FMC_USERNAME, WINGPY_FMC_PASSWORD
  • ISE: WINGPY_ISE_BASE_URL, WINGPY_ISE_USERNAME, WINGPY_ISE_PASSWORD
  • Hyperfabric: WINGPY_HYPERFABRIC_TOKEN

If you do not provide credentials as arguments, the client will look for these environment variables and raise an error if any are missing.

RuntimeError: Cannot run the event loop while another loop is running

This error occurs when you try to run an asynchronous operation in an environment that already has an event loop running (e.g. if you're using FastAPI or asyncio). To fix this, see the concurrency section example.

How do I fetch all results from a paginated API?

Use the get_all() method on APIC, Catalyst Center, FMC, ISE, and Hyperfabric clients. This method will automatically handle paging and return a list of all items.
For ISE, paging is only supported on OpenAPI and ERS endpoints (not XML).
Note: get_all will automatically use concurrency to speed up data retrieval.

How do I run requests concurrently?

All clients have a .tasks attribute (a TaskRunner instance), which lets you schedule requests for concurrent execution. Use .tasks.schedule() to queue up requests, then .tasks.run() to execute them in parallel.
Note: get_all will automatically use concurrency for paging where supported, so you often do not need to manage this manually.

What exceptions should I handle?
  • AuthenticationFailure: Raised if authentication fails (e.g., wrong credentials).
  • InvalidEndpointError: Raised if you use an unsupported or invalid endpoint (e.g., paging on XML in ISE).
  • ValueError: Raised for invalid API endpoint paths (e.g., APIC paths must end with .json or .xml), or if required arguments/environment variables are missing.
  • UnsupportedMethodError: Raised if you call a method not supported by a client (e.g., .put() on a client that doesn't implement it).
How do I use environment variables for configuration?

Set the relevant environment variables before running your script. The client will use them if you do not provide arguments directly. See the authentication question above for variable names.

How do I debug or log requests?

The library uses loguru for logging. You can configure the log level and handlers in your script. Use TRACE or DEBUG for detailed request/response logs. Example: 

from loguru import logger
logger.remove()
logger.add(sys.stderr, level="DEBUG")
Be careful with sensitive data in logs.

How do I know if a method is supported?

Not all clients implement every HTTP method. If you call a method that is not supported, an UnsupportedMethodError will be raised. Supported/unsupported methods are also documented in the API docs, inline in docstrings, and available via IntelliSense in your editor.

How do I customize request headers?

You can set default headers on the .headers attribute of a client instance, or pass headers per request. Setting headers in the constructor is not supported. Example: 

fmc = CiscoFMC(base_url=..., username=..., password=...)
fmc.headers["X-Custom"] = "value"
# or per-request
fmc.get("/api/path", headers={"X-Another": "value"})

How do I handle SSL verification?

The verify argument controls SSL certificate verification. Set verify=False to disable or provide a custom ssl.SSLContext for custom CAs. You can use the built-in ssl module to create a context . Example:

Disable SSL verification
apic = CiscoAPIC(base_url=..., username=..., password=..., verify=False)
Custom SSL context
import ssl
context = ssl.create_default_context()
context.load_verify_locations(cafile="path/to/ca.pem")
ise = CiscoISE(base_url=..., username=..., password=..., verify=context)
Note: Disabling SSL verification is not recommended for production.

How do I set timeouts or retry behavior?

You can set timeout, retries, and other related parameters in the client constructor. Example: 

ise = CiscoISE(base_url=..., username=..., password=..., timeout=30, retries=5)

How do I use the clients as context managers?

All clients support the context manager protocol. Use with to ensure resources are cleaned up: 

with CiscoFMC(base_url=..., username=..., password=...) as fmc:
    fmc.get("/api/path")

How do I check the API version or capabilities at runtime?

Most clients expose a .version attribute after authentication. You can use this to check the API version and adjust your logic accordingly.

How do I handle or debug connection errors?

Connection errors (e.g., network issues, timeouts) will raise exceptions from httpx. Enable debug logging to see more details, and check your network/firewall settings if you encounter persistent issues.