All of our REST APIs are following RESTful API best practices.

Endpoint

There are dozens of data centers managed by ExtremeCloud IQ. Customer data and VIQ data are stored in one of them.

ExtremeCloud IQ provides the uniform API endpoint for users so that they don't need to know which specific RDC to access.

NOTE

All API access are over HTTPS.

Path Templating

Path templating refers to the usage of curly braces {} to mark a section of a URL path as replaceable using path parameters.

HTTP Verbs

Each REST API strives to use appropriate HTTP verbs for different operation wherever possible.

HTTP Verb	Description
GET	Retrieving resources.
POST	Creating resources or calling business operations.
PUT	Replacing resources or creating resources if the resources don't exist.
PATCH	Updating resources with partial JSON data.
DELETE	Deleting resources.

Media Type

All data are sent and received as JSON format if no explicit requirement.

HTTP Headers:

Content-Type: application/json
Accept: application/json

HTTP Status Code

The HTTP Status Codes are used to indicate the status of the executed operations.

Success

Status Code	Description	Use Cases
200	OK	Standard response for successful HTTP requests.
201	Created	The request has been fulfilled, resulting in the creation of a new resource.
202	Accepted	The request is queued for background processing (async tasks or long-running operations).
204	No Content	The server successfully processed the request and is not returning any content.

Client Error

HTTP Status	Description	Use Cases	Client recovery policy
400	Bad Request	The API endpoint exists, but the HTTP request syntax or payload is incorrect, detail will be given in response.	Do not retry. Fix the request.
401	Unauthorized	The server can be reached and understood the request, but refuses to take any further action, because the client must provide authorization. If the client has provided authorization, the server is indicating the provided authorization is unsuitable or invalid.	If the user has not supplied authorization information, prompt them for the appropriate credentials.If the user has supplied authorization information, inform them their credentials were rejected and optionally prompt them again.
403	Forbidden	The server can be reached and understood the request, but refuses to take any further action, because it is configured to deny access for some reason to the requested resource by the client.	Do not retry. Fix the request.
404	Not Found	The API endpoint doesn’t exist or resource doesn’t exist.	Do not retry. Fix the request.
415	Unsupported Media Type	The request entity has a media type which the server or resource does not support.	Do not retry. Fix the request.
429	Too Many Requests	The request entity has a media type which the server or resource does not support.	Retry after a while.

Server Error

HTTP Status Code	Description	Use Cases	Client recovery policy
500	Internal Server Error	Server side Exception caught, detail will be given in response.	Ask user to retry later or the client automatically calls retry request.
503	Service Unavailable	The server is temporary unavailable.	Ask user to retry later or the client automatically calls retry request.

HTTP Response

Successful Response

Successful response is the HTTP response with status code 2xx.

Single resource

Single resource response is object of key-value pairs.

{
  "key1": "...",
  "key2": 10,
  "key3": true
}

Multiple resources

Multiple resource response is the array of objects without pagination information.

[
  {
    "key1": "...",
    "key2": 10,
    "key3": true
  },
  {
    "key1": "...",
    "key2": 11,
    "key3": false
  }
]

Paged resources

Paged resource response is object with pagination information and array of paged objects.

{
  "page": 1,
  "count": 10,
  "total_pages": 100,
  "total_count": 1000,
  "data": [
    {
      "name1": "...",
      "name2": 8,
      "name3": true
    },
    {
      "name1": "...",
      "name2": 6,
      "name3": false
    }
  ]
}

Pagination information:

Name	Required	Description
page	✅	The current page number.
count	✅	The element count of the current page.
total_pages	✅	The total page number based on request page size.
total_count	✅	The total element count.

Unsuccessful Response

Unsuccessful response is the HTTP response with status code 4xx and 5xx.

Unsuccessful response schema

{
  "error_code": "...",
  "error_id": "...",
  "error_message": "..."
}

Name	Required	Description
error_code	✅	The error code, used to classify different error type.
error_id	✅	The unique identifier of the error message, which is used to locate error message in the backend.
error_message	✅	The associated descriptive error message.

Common Fields

Name	Format
Timestamp	ISO 8601 format: YYYY-MM-DDThh:mm:ssZ