ExtremeCloud Appliance :: REST API Gateway (1.13.1)

Download OpenAPI specification:Download

Introduction

The ExtremeCloud Appliance REST API Gateway provides a single entry point between the external requesting clients and the multiple internal APIs that help install, access, manage, and extend applications that are supported by the ExtremeCloud Appliance platform. The Gateway API is based on RESTful principles and uses standard HTTP methods for requests and responses. API request and response bodies are formatted in JavaScript Object Notation (JSON).

You can use any language or library that can submit REST API requests and process JSON to query the Gateway API . Examples of languages and libraries that can build REST clients include:

  • For Java, the Jersey library provides the reference implementation of JAX-RS, a Java standard for RESTful web services. The implementation includes a client library that can run directly on the JVM.
  • For Python, the Requests and JSON libraries facilitate REST API applications.
  • For .Net, the core language provides facilities for submitting HTTP requests, and .Net libraries include a serializer for JSON.
  • For the Linux shell, Wget and cURL can execute REST API calls. Linux shell utilities, like awk and grep, can parse and process JSON.

You can also use tools like Postman, an easy-to-use Chrome extension for making HTTP requests.
Note: To submit API calls, your RESTful API consuming program needs to have logged in using credentials granting at least read permissions. Any administrator account can be used with the REST API but only user accounts with FullAdmin credentials can make configuration changes through the REST API.

Authentication and Authorization

The ExtremeCloud Appliance REST API Gateway supports the HTTP bearer authentication scheme in conjuntion with the OAuth 2.0 protocol to provide secure authorized access to the API. OAuth is an authorization framework that enables web, mobile, and desktop applications to access protected resources. Bearer authentication (aka token authentication) involves security tokens called bearer tokens. To begin, pass your client login credentials within a POST request to the management/v1/oauth2/token endpoint with the following JSON data and structure:

{
   "grantType": "password",
   "userId": "adminUserId",
   "password": "adminPassword",
   "scope": "..."
}

In exchange for these credentials the ExtremeCloud Appliance authorization server issues tokens called bearer tokens that you need to include in the Authorization header when making subsequent REST API calls. Below is a sample response to the token request:

{
    "access_token": "f06f6f285e364e59fd317bd74da9e837",
    "token_type": "Bearer",
    "expires_in": 7200,
    "idle_timeout": 604800,
    "refresh_token": "3e33d8f724e69024811f1cf5869dbaf7",
    "adminRole": "FULL"
}

Note: Access tokens have a finite lifetime. The expires_in field in the response indicates the lifetime, in seconds, of the access token. For example, a value of 7200 indicates that the access token expires in two hours from the time the response was generated. The API endpoint issues a HTTP 401 Unauthorized status code when it detects an expired token.

bearerAuth

Security scheme type: HTTP
HTTP Authorization Scheme bearer

API Request Components

To construct a REST API request, combine the following components:

Component Description
The HTTP method
  • GET: Retrieve data from the server
  • DELETE: Delete a resource from the server
  • POST: Create a new resource on the server
  • PUT: Update an existing resource on the server
The base URL of the API https://{IP_Address}:5825 where {IP_Address} is the IP address of your ExtremeCloud Appliance server instance.
The URI to the resource The resource to create, update, query, or delete. For example, /management/v1/accesscontrol.
Path parameters These variables are part of the full URL path and are used to point to a specific resource within a collection. For example, /v1/controllers/{sn}, where {sn} is the path parameter and is substituted with an actual value when making the API call.
Query string parameters For most REST GET calls, you can specify one or more optional query parameters on the request URI to filter, limit the size of, and sort the data in an API response. Query string parameters appear after a question mark (?) in the endpoint. Each parameter is listed one right after the other with an ampersand (&) separating them. The order of the query string parameters does not matter.
HTTP request headers The following HTTP headers are supported:
  • Accept: Required for operations with a response body, syntax is Accept: application/json
  • Content-Type: Required for operations with a request body, syntax is Content-Type: application/json
  • Authorization: Required to pass Bearer token for all API calls
JSON request body Required for most POST and PUT requests.

When you POST or PUT data to the REST API server, set the Content-Type header to application/json. It can also be useful to set the following request headers:

  • accept: application/json
  • accept-encoding: gzip,deflate,br
  • accept-language: en-US,en;q=0.8,und;q=0.6

Response Codes

The ExtremeCloud Appliance REST API Gateway returns standard HTTP response codes in addition to JSON-based error messages in the response body to help you identify the source of a problem:

HTTP Code Description
200 OK The request was successful
201 Created The resource was created successfully
204 No Content Success with no response body
400 Bad Request The operation failed because the request is syntactically incorrect or violated schema
401 Unauthorized The authentication credentials are invalid or the user is not authorized to use the API
404 Not Found The server did not find the specified resource that matches the request URL
405 Method Not Allowed The API does not support the requested HTTP method

Versioning

The ExtremeCloud Appliance API follows the semantic versioning specification (Major.Minor.Patch). The Major version will be updated whenever we introduce breaking changes. The Minor and Patch versions will be incremented when we add functionality and backward-compatible updates.

AccessControlManager

Create and manage access control list information.

Retrieve access control information

Returns a list of access control information for the customer

Authorizations:

Responses

200

AccessControlMacList details for the customer. The list is empty if the customer does not have access control defined.

default

Error response

get /v1/accesscontrol

ExtremeCloud Appliance REST API Server

https://192.168.3.61:5825/management/v1/accesscontrol

Response samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

Update access control information

Update an existing access control mac list for a customer.

Authorizations:
Request Body schema: application/json

AccessControlMacList instance with parameters to be configured. The instance must have the mandatory attributes like macMode. It can have other optional attributes as well.

One of
  • AbstractEntityCloud
  • AbstractEntityXca
custId
string
id
string <uuid>
macMode
required
number

A flag to indicate switch over between blacklist/whitelist mode. This attribute cannot be null and must be an integer value of 1 or 2.

macList
required
Array of strings

List of black/white listed MAC addresses. If in whitelist mode, only devices on the list are allowed on the network. If in blacklist mode, devices on the list are not allowed on network. Whenever a switchover between white/black happens this list is emptied.

Responses

200

Newly created access control maclist for the customer

default

Error response

put /v1/accesscontrol

ExtremeCloud Appliance REST API Server

https://192.168.3.61:5825/management/v1/accesscontrol

Request samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

Create access control list

Create an access control mac list for a customer.

Authorizations:
Request Body schema: application/json

AccessControlMacList instance with parameters to be configured. The instance must have the mandatory attributes like macMode. It can have other optional attributes as well.

One of
  • AbstractEntityCloud
  • AbstractEntityXca
custId
string
id
string <uuid>
macMode
required
number

A flag to indicate switch over between blacklist/whitelist mode. This attribute cannot be null and must be an integer value of 1 or 2.

macList
required
Array of strings

List of black/white listed MAC addresses. If in whitelist mode, only devices on the list are allowed on the network. If in blacklist mode, devices on the list are not allowed on network. Whenever a switchover between white/black happens this list is emptied.

Responses

201

Newly created access control maclist for the customer

default

Error response

post /v1/accesscontrol

ExtremeCloud Appliance REST API Server

https://192.168.3.61:5825/management/v1/accesscontrol

Request samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

Remove access control list

Deletes an access control mac list for a customer.

Authorizations:
Request Body schema: application/json

AccessControlMacList instance with parameters to be configured. The instance must have the mandatory attributes like macMode. It can also have other optional attributes as well.

One of
  • AbstractEntityCloud
  • AbstractEntityXca
custId
string
id
string <uuid>
macMode
required
number

A flag to indicate switch over between blacklist/whitelist mode. This attribute cannot be null and must be an integer value of 1 or 2.

macList
required
Array of strings

List of black/white listed MAC addresses. If in whitelist mode, only devices on the list are allowed on the network. If in blacklist mode, devices on the list are not allowed on network. Whenever a switchover between white/black happens this list is emptied.

Responses

200

Access control list deleted successfully

default

Error response

delete /v1/accesscontrol

ExtremeCloud Appliance REST API Server

https://192.168.3.61:5825/management/v1/accesscontrol

Request samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "custId": null,
  • "id": null,
  • "canDelete": null,
  • "canEdit": null,
  • "macMode": 1,
  • "macList":
    [
    ]
}

NSightManager

Retrieve and manage NSight server configuration.

Get configuration of NSight server

Authorizations:

Responses

200

Configuration of NSight server

default

Error response

get /v1/nsightconfig

ExtremeCloud Appliance REST API Server

https://192.168.3.61:5825/management/v1/nsightconfig

Response samples

application/json
Copy
Expand all Collapse all
{
  • "ip": "192.168.3.10",
  • "https": true
}

Update configuration of NSight server

Authorizations:
Request Body schema: application/json