ExtremeControl Guest & IoT Manager REST API (v1.0)

Download OpenAPI specification:Download

Introduction

The Guest and IoT Manager (GIM) API allows you to programmatically create, access, and manage onboarding templates, guest users, and guest devices in a simple and secure manner. It 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 GIM 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 and make configuration changes through the REST API, your RESTful API consuming program needs to have logged in using Administrator or Provisioner credentials.

Authentication and Authorization

The GIM API uses the HTTP Basic Authentication scheme for authentication and authorization. You must include a valid Provisioner username and password in username:password format within the Authorization header of your API request. The username and password are encoded with Base64, which is an encoding technique that converts them into a set of 64 characters to ensure safe transmission as part of the Authorization header.

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}/GIM, where {IP_Address} is the address of the Guest and IoT Manager API server.
The URI to the resource The resource to create, update, query, or delete. For example, /rest/onboardingTemplates.
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, /rest/guestUsers/{username}, where {username} 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 make API calls, syntax is Authorization: username:password
  • API Version Custom Header: Required for all requests, syntax is api-version: v1.0
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 GIM REST API 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. The following table lists some common response messages:

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
406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server

Versioning

The GIM REST API implements versioning using a custom request header. You must include the api-version header in your request to specify the version that you want to use for that operation. The current version of the GIM REST API is v1.0.

Getting Started

Creating Onboarding Templates in Guest & IoT Manager

To create onboarding templates:

  • In a browser instance, enter this URL: https://<Guest & IoT Manager IP address>/GIM/admin.
  • Enter the username and password when prompted. The default username and password are admin and admin respectively.
  • Click Onboarding Templates to create the templates. For more information, see the Guest & IoT Manager Configuration Guide.

Creating a Provisioner and Associating it with Onboarding Templates

To create a Provisioner and associate it with existing Onboarding Templates:

  • Log on to Guest & IoT Manager using your default credentials.
  • Click Provisioners to create a Provisioner and associate it with an Onboarding Template. For more information, see the Guest & IoT Manager Configuration Guide.

Authentication

basic_auth

Security scheme type: HTTP
HTTP Authorization Scheme basic

API Information

Retrieve GIM REST API information

Get details about the API, such as base path and version

Responses

200

GIM REST API information

get /rest/apiInfo
https://gim_server_ip_address/GIM/rest/apiInfo

Response samples

application/json
Copy
Expand all Collapse all
{
  • "apiPath": "/rest",
  • "name": "ExtremeControl Guest & IoT Manager REST API",
  • "productName": "ExtremeControl Guest & IoT Manager",
  • "gimVersion": "8.3.0.90",
  • "vendor": "Extreme Networks",
  • "version": "v1.0"
}

Onboarding Template

Retrieve Onboarding Templates associated with a Provisioner

Get list of Onboarding Templates associated with a Provisioner

Authorizations:
header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

List of Onboarding Templates associated with the Provisioner

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

get /rest/onboardingTemplates
https://gim_server_ip_address/GIM/rest/onboardingTemplates

Response samples

Copy
Expand all Collapse all
{
  • "OnboardingTemplates":
    {
    }
}

Retrieve details of a specific Onboarding Template

Retrieve details of a specific Onboarding Template associated with the Provisioner

Authorizations:
path Parameters
onboardingTemplateName
required
string

Name of Onboading Template

header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

Onboarding Template details

400

Onboarding Template is not accessible/invalid

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

get /rest/onboardingTemplateDetails/{onboardingTemplateName}
https://gim_server_ip_address/GIM/rest/onboardingTemplateDetails/{onboardingTemplateName}

Response samples

Copy
Expand all Collapse all
{
  • "OnboardingTemplate":
    {
    }
}

Retrieve custom labels for a guest user

Get custom labels for a guest user

Authorizations:
header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

Guest user custom labels

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

403

Cannot fetch custom labels

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

get /rest/guestUsers/getCustomLabels
https://gim_server_ip_address/GIM/rest/guestUsers/getCustomLabels

Response samples

application/json
Copy
Expand all Collapse all
{
  • "userCustomLabel1":
    {
    },
  • "userCustomLabel2":
    {
    },
  • "userCustomLabel3":
    {
    },
  • "userCustomLabel4":
    {
    },
  • "userCustomLabel5":
    {
    },
  • "userCustomLabel6":
    {
    }
}

Retrieve custom labels for a device

Get custom labels for a device

Authorizations:
header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

Device custom labels

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

403

Could not retrieve custom labels

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

get /rest/devices/getCustomLabels
https://gim_server_ip_address/GIM/rest/devices/getCustomLabels

Response samples

application/json
Copy
Expand all Collapse all
{
  • "deviceCustomLabel1":
    {
    },
  • "deviceCustomLabel2":
    {
    },
  • "deviceCustomLabel3":
    {
    },
  • "deviceCustomLabel4":
    {
    },
  • "deviceCustomLabel5":
    {
    },
  • "deviceCustomLabel6":
    {
    }
}

Devices

Create a new device

Create a new device in the Guest and IoT Manager

Authorizations:
header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Request Body schema: application/json

Device configuration

Device
object

Responses

201

Device created successfully

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device | Invalid input data | Record already exists with the same MAC Address

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

403

Reached maximum license capacity | Maximum limit of enabled devices reached for the Provisioner

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

post /rest/devices
https://gim_server_ip_address/GIM/rest/devices

Request samples

application/json
Copy
Expand all Collapse all
{
  • "Device":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "errorCode": "string",
  • "msg": "string",
  • "property1": { },
  • "property2": { }
}

Retrieve devices based on filter criteria

Get devices based on filter criteria

Authorizations:
query Parameters
field
string
Enum:"macAddress" "deviceName" "source" "deviceTypeGroup" "startDate" "endDate" "onboardingTemplate"

Field to be filtered

oper
string
Enum:"equals" "notEquals" "startsWith" "endsWith" "contains" "greaterThan" "greaterThanEqual" "lessThan" "lessThanEqual"

Operator for filtering

value
string

Value for filtering. For startTime and endTime based filtering, the value should be in the format YYYY/MM/dd hh:mm:ss AM/PM zone-name(Eg., 2018/09/08 10:10:22 AM US/Eastern)

start
number

Start index of the devices

limit
required
number

Maximum number of entries to be filtered

header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

List of devices based on the specified filters

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device | Invalid limit

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

404

Devices not found

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

get /rest/devices
https://gim_server_ip_address/GIM/rest/devices

Response samples

Copy
Expand all Collapse all
{
  • "DeviceList":
    {
    }
}

Delete multiple devices by MAC address

Delete multiple devices by MAC address

Authorizations:
header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Request Body schema: application/json

List of MAC addresses of devices

DevcieList
object

Responses

200

Devices deleted successfully

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

404

Devices not found

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

delete /rest/devices
https://gim_server_ip_address/GIM/rest/devices

Request samples

application/json
Copy
Expand all Collapse all
{
  • "DevcieList":
    {
    }
}

Response samples

Copy
Expand all Collapse all
{
  • "message": "string",
  • "failureList":
    {
    }
}

Update device by MAC address

Update device with the specified MAC Address

Authorizations:
path Parameters
MAC
required
string

MAC address of the device

header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Request Body schema: application/json

Device configuration

Device
object

Responses

200

Device updated successfully

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device | Invalid input data

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

403

Maximum limit of enabled devices reached for the Provisioner

404

Not found

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

put /rest/devices/{MAC}
https://gim_server_ip_address/GIM/rest/devices/{MAC}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "Device":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "errorCode": "string",
  • "msg": "string",
  • "property1": { },
  • "property2": { }
}

Delete device by MAC address

Delete a single device with the specified MAC address

Authorizations:
path Parameters
MAC
required
string

MAC Address of the device

header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

Device deleted successfully

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

404

Device not found

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

delete /rest/devices/{MAC}
https://gim_server_ip_address/GIM/rest/devices/{MAC}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "errorCode": "string",
  • "msg": "string",
  • "property1": { },
  • "property2": { }
}

Retrieve device details by MAC address

Get device details by MAC address for a Provisioner

Authorizations:
path Parameters
MAC
required
string

MAC Address of the device

query Parameters
viewAll
boolean

If the value is true and in the onboarding template, 'Provisioners using this Onboarding Template can view all records of this GIM Domain' checkbox is selected, then the provisioner can view any record

header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

Device details

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device | Invalid input data

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

404

Device does not exist

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout

get /rest/devices/deviceDetails/{MAC}
https://gim_server_ip_address/GIM/rest/devices/deviceDetails/{MAC}

Response samples

Copy
Expand all Collapse all
{
  • "Device":
    {
    }
}

Retrieve N devices from a specificed start index

Get the next set of N devices from a specificed start index, with or without details

Authorizations:
query Parameters
start
required
number

The starting index of the device list

limit
required
number

Maximum number of entries

hideDetails
boolean

When true, the device details are not specified in the response

header Parameters
api-version
required
string
Default: "v1.0"

REST API version

Responses

200

List of N devices from the specified start index

400

Onboarding Template is not accessible/invalid | Does not have permission to provision the device | Invalid limit

401

Missing Authorization header | Invalid credentials | Provisioner is not associated with any REST API Onboarding Template

404

Devices not found

406

Missing version | Invalid version format | Version not supported

500

Internal server error

503

Radius error | Access Control Engine not reachable | Request timeout