REST API Overview

The OS provides a RESTful API interface that allows programmatic access to switch configuration and operational data. The REST API enables automation, integration with third-party tools, and custom application development without requiring CLI or web-based interaction.

API Architecture

The ExtremeXOS REST API is based on industry-standard HTTP/HTTPS protocols and follows RESTful design principles. API requests use standard HTTP methods (GET, POST, PUT, DELETE, PATCH) to perform operations on switch resources.

The API is accessible through the OpenAPI server, which runs alongside other web-based interfaces on the switch:

All services coexist on standard HTTP (port 80) and HTTPS (ports 443, 9443) using URI-based path multiplexing.

Accessing the API

Before using the REST API, you must enable the OpenAPI server. On Universal Platforms, use the following command:

enable openapi

Once enabled, the API is accessible at:

For detailed information about managing the OpenAPI server, including enabling, disabling, restarting, and monitoring server status, see Managing the OpenAPI Server.

Authentication

API requests require authentication using token-based authentication. The authentication workflow consists of two steps:

  1. Obtain an authentication token: Send a POST request to /auth/token with your username and password: 
    POST http://<switch-ip>/auth/token
Content-Type: application/json

{
  "username": "admin",
  "password": ""
}

    The response includes an authentication token and its time-to-live (TTL):

    {
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "ttl": 86400
}
  2. Use the token in subsequent requests: Include the token in the x-auth-token header: 
    GET http://<switch-ip>/rest/openapi/v0/state/system
x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Tokens remain valid for the configured TTL period (default 24 hours). After expiration, you must obtain a new token. For information about configuring token TTL, see Configurable Web Authentication Token Time-to-Live.

Tip

Tip

Use HTTPS for all API communication to protect authentication tokens and sensitive data in transit.

API Endpoints and Operations

The REST API provides access to switch resources through structured URIs. Common resource categories include:

HTTP methods correspond to operations on resources:

Example operations:

# Get system information
GET /rest/openapi/v0/state/system

# Get VLAN configuration
GET /rest/openapi/v0/config/vlans

# Create a VLAN
POST /rest/openapi/v0/config/vlans
Content-Type: application/json

{
  "name": "finance",
  "tag": 100
}

# Modify port configuration
PATCH /rest/openapi/v0/config/ports/1
Content-Type: application/json

{
  "admin-state": "enabled",
  "description": "Server Connection"
}

API Documentation and Schema

Complete API documentation, including available endpoints, request/response formats, and data models, is available through the OpenAPI schema. Once the OpenAPI server is enabled, access the schema at:

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

The schema provides:

The schema follows the OpenAPI Specification (formerly Swagger), which is widely supported by API development tools and client libraries.

Request and Response Format

The API uses JSON (JavaScript Object Notation) for request and response bodies. All requests and responses must include appropriate Content-Type headers:

Request headers:

Content-Type: application/json
x-auth-token: <your-token>

Response format:

Successful operations return HTTP status codes in the 200 range along with response data in JSON format. Common success codes include:

Error conditions return HTTP status codes in the 400 or 500 range along with error details:

Error responses include descriptive messages to help diagnose issues:

{
  "error": {
    "code": 404,
    "message": "VLAN 'invalid-vlan' not found"
  }
}

Common Use Cases

Network Automation:

Use the REST API with automation tools like Ansible to deploy consistent configurations across multiple switches, perform automated backups, or implement configuration templates.

Custom Monitoring:

Integrate with monitoring platforms to collect switch statistics, port status, or system health metrics. Build custom dashboards or alerting systems based on real-time switch data.

Configuration Management:

Implement configuration management workflows using version control systems. Store switch configurations as JSON, track changes over time, and automate configuration deployment.

Integration with IT Systems:

Integrate switch management with ticketing systems, asset management databases, or enterprise service management platforms. Automate provisioning workflows triggered by external systems.

Custom Applications:

Develop custom applications or scripts using Python, JavaScript, or other languages to interact with switches programmatically. Build specialized tools for your specific operational needs.

Client Libraries and Tools

Several tools and libraries facilitate REST API interaction:

Command-line tools:

Programming language libraries:

API development tools:

Example using curl:

# Get authentication token
curl -X POST http://192.168.1.1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":""}'

# Use token to get system state
curl -X GET http://192.168.1.1/rest/openapi/v0/state/system \
  -H "x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Example using Python requests library:

import requests
import json

# Get authentication token
auth_response = requests.post(
    'http://192.168.1.1/auth/token',
    json={'username': 'admin', 'password': ''}
)
token = auth_response.json()['token']

# Get system state
headers = {'x-auth-token': token}
response = requests.get(
    'http://192.168.1.1/rest/openapi/v0/state/system',
    headers=headers
)
system_info = response.json()
print(json.dumps(system_info, indent=2))

Best Practices

Troubleshooting

Cannot connect to API:

Authentication failures:

400 Bad Request errors:

404 Not Found errors:

Server errors (500 range):

Additional Resources

9039574-00 Rev AA