Xi Frame Admin API

Introduction

The Xi Frame Admin API service is based on standard RESTful HTTPS calls. All API endpoints require signed authentication via HTTP headers.

The typical workflow for an API call is as follows:

  1. Authenticate with the Frame RESTful API to sign the HTTPS API request. You’ll need to create a signature with the client_id, the client_secret, and a timestamp. The client_id and client_secret can be acquired by any Admin on Frame.
  2. Make the HTTPS REST call to the Admin API endpoint using the client_id, timestamp, and the signature in the HTTP header (Created in step 1a).
  3. The Frame RESTful API verifies the signature of the HTTPS request and will then send the response of the previous call.

Getting Started

Your Xi Frame Admin API endpoint will be unique to your environment and in the following format:

https://api-gateway-prod.[frame-environment-domain].com/v1

For Xi Frame’s public environment, this URI is:

https://api-gateway-prod.frame.nutanix.com/v1

In the next section, we will review how to properly authenticate to be able to use the Xi Frame Admin API.

API Authentication

All RESTful API calls require authentication for each 3rd party service (individual users are not currently supported) and all API calls require signed requests for authentication.

Each API request must be signed and include the necessary information for proper signature verification. To sign an API request call, a client_id and client_secret are required to generate a signature and are also used for signature verification.

How to Provision API Credentials

  1. Navigate to the admin view of your Xi Frame account.

  2. Locate the desired Account/Organization/Customer entity using the menu on the left. Click on the entity name and navigate to the “Authentication” tab listed under “Security.”

  3. Enable the API Authentication option and click “Save.” This will create a new tab entitled “API.”

    ../_images/overview_1.png
  4. Go to the newly created API Authorizations tab and click “Add API.”

    ../_images/overview_2.png
  5. Enter a name for the API Authorization and choose the role(s) you would like to grant the API key at the bottom. Roles determine the permission level of the API. Click “Add.”

    ../_images/overview_3.png
  6. Click the ellipsis next to the API Authorization you just created and select “Manage Credentials.”

    ../_images/overview_4.png
  7. Name the API Key and then click the plus symbol to create it.

    ../_images/overview_5.png
  8. Record the client_Id and client_Secret to be used by your API calls.

    Warning

    Make sure to record this information, as it will only appear once. You will not be able to retrieve these details again.

    ../_images/overview_6.png

How to Make API Calls

In the last section, you generated a client_id and a client_secret.

The client_id is a unique string that Frame’s Admin API uses for client/service identification. It is used by the authentication system to identify the proper account and API client permissions.

The client_secret is an HMAC-SHA256 key used to generate the signature and is required by the signature verification process.

A signature is created by applying the HMAC-SHA256 algorithm to a string that is constructed from the client_id and a timestamp. The timestamp is the current time in seconds since epoch.

The proper steps for creating a signature are as follows:

  1. Get the current timestamp.
  2. Create a string by concatenating the timestamp with the client_id (timestamp + client_id).
  3. Apply HMAC-SHA256 on the newly created string using the client_secret

In order to verify the signature, our API requires the newly created signature, the client_id, and the timestamp. The client_secret should NOT be included. This information should be sent in the HTTP request headers.

Below is a simple example of a python script that can be used to generate the signature needed for the API call and then the HTTPS request.

#!/bin/env python

import hashlib
import hmac
import time
import requests
import base64

# Client credentials

client_id = "cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.frame.nutanix.com"
client_secret = "5891b5b522d5XXXXXXXXXXXXXXXXXXXXXXXXXX7163af34d08XXXXXe846f6be03"

# Create signature
timestamp = int(time.time())
to_sign = "%s%s" % (timestamp, client_id)
signature = hmac.new(client_secret, to_sign, hashlib.sha256).hexdigest()

# Prepare http request headers
headers = { "X-Frame-ClientId": client_id, "X-Frame-Timestamp": str(timestamp), "X-Frame-Signature": signature }

# Make request
r = requests.get("https://api-gateway-prod.frame.nutanix.com/v1/accounts", headers=headers)
accounts = r.json()
for account in accounts:
  print account

List Accounts

Lists all accounts for a user, based on the user token.

GET /accounts/${id}

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts"

Response Example

Status: 200 OK
[
  {
    "website": null,
    "name": "Aca Ivic Local",
    "last_publish": "2018-07-12T11:26:18.879116",
    "id": "b614cb6f-796b-4371-86cb-465d6dfc433b",
    "description": null,
    "active": true
  }
]

Publish a Sandbox

Starts the publish action for an account’s Sandbox and returns the pending request ID.

POST /accounts/${id}/publish

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/publish"

Response Example

Status: 200 OK
{
  "pending_request": {
    "id": "0c956d69-9700-4e80-b1ee-5179f5b5a3de"
  }
}

List Publish Tasks

Lists publishing tasks for the given account ID.

GET /accounts/${id}/publish/tasks

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/publish/tasks"

Response Example

Status: 200 OK
[
  {
    "status": "provisioning",
    "number_of_instances": 1,
    "last_change": "2018-07-25T04:30:09",
    "id": 391
  }
]

Get Publish Status

Returns the publishing status for a given account ID and publish request ID.

GET /accounts/${id}/publish/${request_id}

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True
request_id Request the ID of a publish URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/publish/${request_id}"

Response Example

Status: 200 OK
{
  "status": "in_progress",
  "id": "793db0f3-31f7-4cc1-8cd5-741c80407aba"
}

Cancel Publish

Cancels a publishing request for the given account ID and publish request ID.

DELETE /accounts/${id}/publish/${request_id}

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True
request_id Request the ID of a publish URL String True

Request Example

curl -X DELETE \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/publish/${request_id}"

Response Example

Status: 202 Accepted
{}

List Applications

Returns a list of applications for the account specified.

GET /accounts/${id}/applications

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/applications"

Response Example

Status: 200 OK
[
  {
    "working_directory": null,
    "path": "C:\\Program Files\\Frame\\FrameExplorer\\FrameExplorer.exe",
    "name": "Frame Explorer",
    "is_updated": false,
    "is_published": true,
    "is_deleted": false,
    "id": "909b74cc-d207-47ed-bd25-2b8088c36912",
    "icon_url": "https://next-cpanel-dev.s3.amazonaws.com/images/apps/frame_explorer.png",
    "arguments": null
  },
  {
    "working_directory": null,
    "path": "C:\\Program Files(x86)\\Google\\Chrome\\Application\\chrome.exe",
    "name": "Google Chrome",
    "is_updated": false,
    "is_published": true,
    "is_deleted": false,
    "id": "e288cac6-87c6-4dcf-bd19-5287f571e774",
    "icon_url": "https://next-cpanel-dev.s3.amazonaws.com/images/apps/google_chrome.png",
    "arguments": null
  },
  {
    "working_directory": null,
    "path": "C:\\Windows\\system32\\notepad.exe",
    "name": "Notepad",
    "is_updated": false,
    "is_published": true,
    "is_deleted": false,
    "id": "547e2eeb-7d6c-4ec8-976e-d0677f23322b",
    "icon_url": "https://next-cpanel-dev.s3.amazonaws.com/images/apps/notepad.png",
    "arguments": null
  }
]

List Session Reports

Returns a list of generated session reports.

GET /accounts/${id}/session_reports

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/session_reports"

Response Example

Status: 200 OK
[
  {
    "year": 2018,
    "url": "https://s3-datest.dev.fra.me/datest-session-reports/datest/9rnKxGPdbozby6YA.2018.7.4311c.31.csv.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Credential=QazWsxEdc777%2F20180724%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20180724T101921Z&X-Amz-Signature=b77249805c20ddd45d2c38ffed5af6284ee34c57defb33f46911c10ace82dccf",
    "month": 7
  }
]

List Active Sessions

Returns a list of active sessions for all pools on a specified account.

GET /accounts/${id}/active_sessions

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/active_sessions"

Response Example

Status: 200 OK
[
  {
    "wait_for_instance": false,
    "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
    "state": "open",
    "start_time": 1532435960,
    "server_ws_port": "443",
    "server_address": "datest-18-185-108-165.dev.fra.me",
    "pool_id": "gw-dev.7116",
    "location_distance": -1,
    "location_country": null,
    "location_city": null,
    "is_https_connection": true,
    "instance_status": null,
    "id": "gw-dev.xjVbYREPlvZWpvPE",
    "gateway": "gw-dev"
  }
]

List Recent Sessions

Returns a list of sessions for a given period of time.

GET /accounts/${id}/recent_sessions

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True
from_date Defaults to today, format YYYY-MM-DD URL String False
to_date Defaults to today, format YYYY-MM-DD URL String False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/recent_sessions?from_date=2018-01-01&to_date=2018-08-17"

Response Example

Status: 200 OK
[
  {
    "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
    "timeouts": {
      "max_duration": 3600,
      "idle": 600,
      "connection": 120
    },
    "state": "failed",
    "start_time": "2018-07-24T03:27:24",
    "session_duration": 3693,
    "server": {
      "wsport": null,
      "pool_group_type": "sandbox",
      "instance_type": null,
      "https": true,
      "address": null
    },
    "location": {
      "distance": -1,
      "country": "",
      "client_ip": "127.0.0.1",
      "city": ""
    },
    "id": "gw-dev.6qn85Z86pk4Pdzla",
    "hash_id": "gkb67zxLRgzAOK4j",
    "end_time": null
  }
]

Get Session

Returns information regarding a specific session.

GET /accounts/${account_id}/sessions/${session_id}

Request Parameters

Parameter Description Param Type Data Type Required
account_id ID of an account URL String True
session_id ID of a session URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${session_id}/sessions/${session_id}"

Response Example

Status: 200 OK
{
  "wait_for_instance": false,
  "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
  "state": "failed",
  "start_time": 1532428044,
  "server_ws_port": null,
  "server_address": null,
  "pool_id": "gw-dev.6526",
  "location_distance": -1,
  "location_country": null,
  "location_city": null,
  "is_https_connection": true,
  "instance_status": null,
  "id": "gw-dev.6qn85Z86pk4Pdzla",
  "gateway": "gw-dev"
}

Stop a Session

Stops the specified session.

DELETE /accounts/${account_id}/sessions/${session_id}

Request Parameters

Parameter Description Param Type Data Type Required
account_id ID of an account URL String True
session_id ID of a session URL String True

Request Example

curl -X DELETE \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${session_id}/sessions/${session_id}"

Response Example

Status: 200 OK
{
  "wait_for_instance": false,
  "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
  "state": "open",
  "start_time": 1532428044,
  "session_request_url": null,
  "server_ws_port": null,
  "server_address": null,
  "pool_id": "gw-dev.6526",
  "location_distance": -1,
  "location_country": null,
  "location_city": null,
  "is_https_connection": true,
  "instance_status": null,
  "id": "gw-dev.6qn85Z86pk4Pdzla",
  "gw_id": 4196,
  "gateway": "gw-dev",
  "cancel_request_url": null,
  "automation_request_id": null
}

Get Sandbox Status

Returns the status of a Sandbox pool on a specified account.

GET /accounts/:id/sandbox/status

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/sandbox/status"

Response Example

Status: 200 OK
{
  "user_sessions": {},
  "status": "server_available",
  "running_servers": 0,
  "pool_type": null,
  "pool_group_id": 6449,
  "min_servers": 0,
  "max_servers": 1,
  "maintenance": "none",
  "instance_type": 2,
  "id": "gw-dev.7116",
  "gateway": "gw-dev",
  "buffer_servers": 0,
  "available_servers": 0,
  "active_servers": -3
}

Start a Sandbox

Starts the Sandbox server on a specified account.

POST /accounts/${id}/sandbox/start

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/sandbox/start"

Response Example

Status: 202 Accepted
{}

Stop a Sandbox

Stops the Sandbox server on specified account.

POST /accounts/${id}/sandbox/stop

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/sandbox/stop"

Response Example

Status: 202 Accepted
{}

Reboot a Sandbox

Reboots the Sandbox server on a specified account.

POST /accounts/${id}/sandbox/reboot

Request Parameters

Parameter Description Param Type Data Type Required
Id ID of an account URL String True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/sandbox/reboot"

Response Example

Status: 200 OK
{
  "server": {
    "ssd": true,
    "private_ip": "10.0.34.88",
    "status": "rebooting",
    "debug": false,
    "name": "Coa Local 1 - 239259",
    "reserved": -1,
    "fault": 0,
    "last_change": "2018-07-25T03:19:08",
    "logging": false,
    "resources_allocated": true,
    "active": false,
    "spot_instance": false,
    "problem": false,
    "maintenance": false,
    "machine_name": "ip-0A002258",
    "local_ip": "18.185.108.165",
    "zone": "eu-central-1b",
    "recovery": false,
    "desired_status": "running",
    "datacenter": 6,
    "has_runs": true,
    "local_wsport": "443",
    "pending_upgrades": 0,
    "domain_joined": false,
    "instance_type": 2,
    "launch_time": "2018-07-24T12:30:08",
    "in_use": false,
    "upgrade_version": 100017,
    "public_port": "8112",
    "creation_time": "2018-07-24T05:30:07",
    "pending_upgrades_with_reboot": 0,
    "aws_instance_id": "i-0008e108ce39940dd",
    "id": 239259
  },
  "pending_request": {
    "id": "439f177b-d89f-4f6a-904f-97f13948e457"
  }
}

Get Account Usage

Returns usage information for an account within a specified time period.

GET /accounts/${id}/usage

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True
from_date Defaults to today, format YYYY-MM-DD URL String True
to_date Defaults to today, format YYYY-MM-DD URL String True
resolution_type Defaults to: by_hour, options: by_hour | by_day | by_month | by_year Header String False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
-H "resolution_type: by_day" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/usage?from_date=2018-01-01&to_date=2018-08-20"

Response Example

Status: 200 OK
{
  "usage_data": {
    "vendor_id": 1338,
    "usage": [
      {
        "time": 1532217600000,
        "server_type_id": "sandbox",
        "instance_type": {
          "name": "t2.medium",
          "id": 4
        },
        "hours_used": 1,
        "datacenter": {
          "name": "aws-de",
          "id": 6,
          "geo_long": 8.683333,
          "geo_lat": 50.116667
        }
      },
      {
        "time": 1532253600000,
        "server_type_id": "sandbox",
        "instance_type": {
          "name": "t2.medium",
          "id": 4
        },
        "hours_used": 1,
        "datacenter": {
          "name": "aws-de",
          "id": 6,
          "geo_long": 8.683333,
          "geo_lat": 50.116667
        }
      }
    ],
    "gateway_id": "gateway-web-datest.dev.fra.me"
  },
  "status_message": "Success.",
  "status": 0,
  "resolution": "by_hour",
  "credited_data": {
    "vendor_id": 1338,
    "gateway_id": "gateway-web-datest.dev.fra.me",
    "credit": [
      {
        "time": 1532253600000,
        "server_type_id": null,
        "instance_type": {
          "name": "t2.medium",
          "id": 4
        },
        "datacenter": {
          "name": "aws-de",
          "id": 6,
          "geo_long": 8.683333,
          "geo_lat": 50.116667
        },
        "credited_hours": 2
      }
    ]
  }
}

Get Session Count

Returns the session count for a specified account in a specified time period.

GET /accounts/${id}/disk_volume_usage

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True
from_date Defaults to today, format YYYY-MM-DD URL String True
to_date Defaults to today, format YYYY-MM-DD URL String True
resolution_type Defaults to: by_hour, options: by_hour | by_day | by_month | by_year Header String False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
-H "resolution_type: by_day" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/disk_volume_usage?from_date=2018-01-01&to_date=2018-08-20"

Response Example

Status: 200 OK
[
     {
       "hours_used": 744,
       "datacenter": "aws-de",
       "time": 1448928000000,
       "disk_volume_type_id": "gp2",
       "disk_volume_size_used": 29760
     },
     {
       "hours_used": 744,
       "datacenter_id": "aws-de",
       "time": 1451606400000,
       "disk_volume_type_id": "gp2",
       "disk_volume_size_used": 29760
     }
]

Get API Authorization Rules

Returns authorization rules for the account, organization, and customers, respectively.

GET /accounts/${id}/api_authorization_rules
GET /organizations/${id}/api_authorization_rules
GET /customers/${id}/api_authorization_rules

Request Parameters

Parameter Description Param Type Data Type Required
id ID of an account URL String True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api-gateway-prod.frame.nutanix.com/v1/accounts/${id}/api_authorization_rules"

Response Example

Status: 200 OK
[
  {
    "roles": [
      {
        "role": {
          "permissions": [
            "..."
          ],
          "name": "Account Administrator",
          "description": null,
          "applicable_on": "account"
        },
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    ],
    "name": "thang2",
    "id": 8,
    "credentials": [
      {
        "name": "thang2_key",
        "client_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.img-external-api-nfstg.frame-publicsector.com"
      }
    ],
    "api_authorization_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  },
  {
    "roles": [
      {
        "role": {
          "permissions": [
            "..."
          ],
          "name": "Account Administrator",
          "description": null,
          "applicable_on": "account"
        },
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    ],
    "name": "thang",
    "id": 7,
    "credentials": [
      {
        "name": "thang_key",
        "client_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.img-external-api-nfstg.frame-publicsector.com"
      }
    ],
    "api_authorization_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
]