Managing the OpenAPI Server

Version 33.6.1 adds user-accessible commands to manage the OpenAPI server on Universal Platforms. The OpenAPI server provides RESTful API access for integration with third-party management tools such as Ansible, while maintaining compatibility with IQAgent cloud management.

OpenAPI Server Overview

The OpenAPI server provides programmatic access to switch configuration and state via a RESTful API. Previously managed exclusively by IQAgent for internal cloud applications, the OpenAPI server is now available for customer use.

The OpenAPI server operates alongside other web-based interfaces on the switch:

Chalet: Web-based management interface (root path /)
OpenAPI: RESTful API interface (/rest/openapi)
RESTCONF: RESTCONF protocol interface (/rest/restconf)
Authentication: Token generation (/auth/token)

The web server multiplexes these applications based on URI paths, allowing all services to coexist on standard HTTP (port 80) and HTTPS (ports 443, 9443). There are no changes to existing enable web http or enable web https commands.

Enabling the OpenAPI Server

To enable the OpenAPI server for third-party tool integration:

enable openapi

Once enabled, the OpenAPI server accepts RESTful API requests at:

http://<switch-ip>/rest/openapi
https://<switch-ip>/rest/openapi
https://<switch-ip>:9443/rest/openapi

The OpenAPI server state persists across reboots.

Disabling the OpenAPI Server

To disable the OpenAPI server when it is not needed:

disable openapi

This stops the OpenAPI server process and prevents API access via the /rest/openapi URI path.

IQAgent Override:

When IQAgent is enabled, the OpenAPI server is required for cloud connectivity and cannot be disabled by the user. Attempting to disable the server when IQAgent is enabled displays:

Note: The OpenAPI server is required by IQAgent and will remain operational 
while IQAgent is enabled.

The server remains running and the state shows as "Enabled (by IQAgent)". To disable the OpenAPI server when IQAgent is enabled, you must first disable IQAgent.

Restarting the OpenAPI Server

To restart the OpenAPI server process:

restart process openapi

Restarting may be necessary to:

Apply configuration changes that require a restart
Recover from an unhealthy or failed server state
Clear temporary issues or reset connections
Apply debug mode changes

During the restart, API access via the /rest/openapi URI path is temporarily unavailable. Schedule restarts during maintenance windows when possible to minimize impact on integrated management tools.

Viewing OpenAPI Server Status

To view the current state and operational status of the OpenAPI server:

show openapi

Sample output when enabled by user:

State            : Enabled (by user)
Server Status    : Healthy
Version          : 1.4.12.16
Schema Version   : 0.2.0

Sample output when IQAgent requires OpenAPI:

State            : Enabled (by IQAgent)
Server Status    : Healthy
Version          : 1.4.12.16
Schema Version   : 0.2.0

Sample output when disabled:

State            : Disabled
Server Status    : Stopped
Version          : 1.4.12.16
Schema Version   : 0.2.0

Output Fields:

State: Whether the server is enabled (and by whom) or disabled
- Enabled (by user) - Enabled via user command
- Enabled (by IQAgent) - Required by IQAgent
- Enabled (by IQAgent and user) - Both enabled it
- Disabled - Server is not running
Server Status: Current operational status
- Healthy - Running normally
- Unhealthy - Running but experiencing issues
- Booting - Starting up
- Stopped - Not running
- Failed - Failed to start or crashed
Version: Semantic version of the OpenAPI application (N/A if unavailable)
Schema Version: Semantic version of the NOS-OpenAPI YAML schema (N/A if unavailable)

To display HTTPS (SSL) related port information, use the show web command.

# show web
HTTP
    Access         : Disabled
    Port number(s) : 80
    Access profile : not set
 
HTTPS
    Access         : Enabled
    Port number(s) : 443, 9443
 
Authentication token default TTL: 60 seconds

Integration with Management Tools

The OpenAPI server enables integration with third-party automation and management tools. Common use cases include:

Ansible: Use Ansible playbooks to automate switch configuration and management via the OpenAPI
Python scripts: Develop custom automation scripts using Python with RESTful API calls
Monitoring systems: Integrate with monitoring platforms to collect switch state and performance data
Configuration management: Implement configuration management workflows using standard REST APIs

Refer to the OpenAPI schema documentation for details on available API endpoints, request formats, and response structures.

Authentication

API requests to the OpenAPI server require authentication. Use token-based authentication by first obtaining an authentication token from the /auth/token endpoint, then include the token in subsequent API requests via the x-auth-token header.

See Configurable Web Authentication Token Time-to-Live for information on configuring token time-to-live settings.

Best Practices

Enable the OpenAPI server only when actively using third-party tools that require API access
Use HTTPS (ports 443 or 9443) for API access to ensure encrypted communication
Implement proper authentication and authorization in your API client applications
Monitor server status when integrating new tools to detect potential issues early
Schedule server restarts during maintenance windows to minimize impact on automation workflows
Keep debug mode disabled during normal operation to avoid excessive logging