Frame Developer Hub

The Developer documentation Developer Hub

Welcome to the Developer documentation developer hub. You'll find comprehensive guides and documentation to help you start working with Developer documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Web API

Suggest Edits

General

Frame’s web 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 Web API Gateway to sign the HTTPS API request
    a. Create a signature with the client_id, the client_secret , and a timestamp (The client_id and client_secret are provided by Frame)
  2. Make the HTTPS REST call to the Web API resource endpoint using the client_id, timestamp, and the signature in the HTTP header (Created in step 1a)
  3. The Frame Web API Gateway verifies the signature of the HTTPS request and will then send the response of the previous call

Additional Notes:

API Authentication

All Gateway API calls require authentication for each 3rd party service (use by individual users is 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.

To provision your API credentials:

Login as your Platform Ultimate account. Credentials apply by Platform Ultimate Account, so if you have multiple Platform Ultimate accounts, you will need credentials for each one.

Go to the Account menu

Scroll to API Credentials and select "Add New"

Select All and Click ADD.

The new ID and credentials will appear. Be sure to copy them now because they will not be shown again. If you lose your credentials, you can create new API credentials and delete the old ones.

The client_id is a unique string that Frame’s 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 required by the signature verification process.

A signature is created by applying the HMAC-SHA256 algorithm on 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 would be:

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

In order to verify the signature, the API Gateway 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.

Simple Example

#!/bin/env python

import hashlib
import hmac
import time
import requests
import base64

# Client credentials

client_id = "cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com"
client_secret = "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03"

# 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.fra.me/v1/accounts", headers=headers)
accounts = r.json()
for account in accounts:
  print account

$clientId = "SOME_ID.img.mainframe2.com"
$clientSecret = "SOME_SECRET"
 
$timestamp = [int](Get-Date -UFormat %s)
$toSign = "$timestamp$clientId"

 
$hmac = new-object System.Security.Cryptography.HMACSHA256
$hmac.Key = [Text.Encoding]::ASCII.GetBytes($clientSecret)
$signature = $hmac.ComputeHash([Text.Encoding]::ASCII.GetBytes($toSign))
$signature = [System.BitConverter]::ToString($signature)

$signature = [System.Text.RegularExpressions.Regex]::Replace($signature, "-", "").ToLower()

$stringTime = [string]($timestamp)
 
$headers = @{}
$headers.Add("Host", "api.fra.me") # Not strictly necessary
$headers.Add("X-Frame-ClientId", $clientId)
$headers.Add("X-Frame-Timestamp", $stringTime)
$headers.Add("X-Frame-Signature", $signature)
 
$response = Invoke-WebRequest -Uri "https://api.fra.me/v1/accounts" -Method GET -Headers $headers
 
Write-Host $response

back to top

Analytics And Account Information

Accounts

This resource endpoint is used for managing vendor accounts and all related resources.

List accounts
GET /v1/accounts/ HTTP/1.1

This call will list all accounts owned by a Frame Platform Ultimate (Super Admin) account (associated with the client_id). The response includes the account name, account ID (the account ID is required by other API calls) and the account admin email which is often used as an external identifier by other systems.

To make this call, you will need to send an HTTPS GET request to the /v1/accounts/ path.

GET https://api.fra.me/v1/accounts/ HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
  {
    "account_id": "xxxxxxxxxx",
    "name": "Superadmin",
    "email": "[email protected]"
  },
  {
    "account_id": "yyyyyyyyyy",
    "name":"bizAdmin",
    "email": "[email protected]"
  }
]

back to top

Session Reports

The sessions resource endpoint is used for reporting on session activity on an account that belongs to a specific Super Admin account.

Note The account ID is required for this call. To retrieve the account ID, you must first call the /v1/accounts/ API to retrieve a list of your accounts and their associated account IDs.

List Sessions
GET /v1/accounts/<account_id>/sessions HTTP/1.1

Each call to this API will generate a list of links for reports on account session activity along with key data points (links will be generated for each month in CSV format). To get the list of session links, an HTTP GET request must be called at /v1/accounts/<account_id>/sessions path.

GET https://api.fra.me/v1/accounts/<account_id>/sessions HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
  {
    "url": "https://session-reports.s3.amazonaws.com/p01/BaEnVDpRkje9KZLv.2016.1.506c0.csv.zip?Signature=xxxxx12345&Expires=1470306685&AWSAccessKeyId=zzzzzzzzzz",
    "month": 1,
    "year": 2016
  },
  {
    "url": "https://session-reports.s3.amazonaws.com/p01/BaEnVDpRkje9KZLv.2016.2.c1676.csv.zip?Signature=yyyyy12345&Expires=1470306685&AWSAccessKeyId=zzzzzzzzzz",
    "month": 2,
    "year": 2016
  },
  {
    "url": "https://session-reports.s3.amazonaws.com/p01/BaEnVDpRkje9KZLv.2016.3.e0645.csv.zip?Signature=zzzzz12345&Expires=1470306685&AWSAccessKeyId=zzzzzzzzzz",
    "month": 3,
    "year": 2016
  }
]

back to top

Recent Sessions

GET /v1/accounts/<account_id>/recent_sessions

Returns a list of sessions that were closed within last 24 hours and which have not yet been added to the monthly CSV file.This CSV file has the same structure as monthly CSV session reports.

Example Request:

GET /v1/accounts/<account_id>/recent_sessions HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

HTTP 200 OK
Vary: Accept
Content-Type: text/csv
Content-Disposition: attachment; filename="Wr1qgbPa99Pal7E8.recent_sessions.csv"

"username","application","geo_distance","city","starttime","session_duration","state","avg_bandwidth","avg_latency","avg_video_bitrate","avg_framerate","resolution","user_agent","remote_ip","system_type","session_type","additional_apps","user_data","account_email","account_name","account_id","region","country","session id","storage used"
....DATA...

back to top

Usage

The usage resource endpoint lists the total number of hours used by a specific account.

List usage hours

GET

To generate the list of usage hours, an HTTPS request must be sent to the relative /v1/accounts/<account_id>/usage path.

Note The account ID is required for this call. To retrieve the account ID, you must first call the /v1/accounts/ API to retrieve a list of your accounts and their associated account IDs.

GET /v1/accounts/xxxxxxxxxx/usage?date_from=2016-08-10&date_to=2016-08-11 HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
  {
    "datacenter":"aws-va",
    "time":"2016-08-10T00:00:00",
    "hours_used":1,
    "instance_type":"g2.2xlarge",
    "server_type":"production"
  },
  {
    "datacenter":"aws-va",
    "time":"2016-08-10T00:00:00",
    "hours_used":3,
    "instance_type":"t2.small",
    "server_type":"utility"
  }
]

Usage Date Range

To filter the results on a range of dates, the parameters date_from and date_to should be passed. Both fields are formatted in the date ISO format (yyyy-MM-dd) and specified in the PST time zone.

Note that the time returned in the time property is also in the PST time zone.

The date_from and date_to parameters are optional. The date_from default value is 1970-01-01 and the date_to default value is NOW.

Parameters:

ParameterFormat
date_fromyyyy-MM-dd
date_toyyyy-MM-dd

back to top

Team Members

The team members resource endpoint lists the team members that are associated with a particular Frame account.

List team members
GET

To generate the list of team members, an HTTPS request must be sent to the relative /v1/accounts/<account_id>/team_members path. The list returned includes the name, email address, and status for each of the users attached to an account.

GET /v1/accounts/xxxxxxxxxx/team_members
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
    {"name":"AAA BBB","email":"[email protected]","status":"active"},
    {"name":"CCC DDD","email":"[email protected]","status":"pending"},
    {"name":"EEE FFF","email":"[email protected]","status":"active"},
    {"name":"GGG HHH","email":"[email protected]","status":"pending"}
]

back to top

Applications

The Applications endpoint lists the applications for an account, the application published status, name and a link to the application icon.

GET /v1/accounts/xxxxxxxxxx/applications
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
  {
      "id":"s3Jh4cFw",
      "icon":"https://d1knahqv5nsneo.cloudfront.net/app_icons/images/000/007/474/thumb/802998139abaab9bc71e2571b7de4825.png?1465215997",
      "name":"Google Chrome",
      "path":"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
      "environment": "production"
  },
  {
      "id":"Dg4L2pa8",
      "icon":"https://d2epwtt5qaqjh1.cloudfront.net/app_icons/images/000/000/004/thumb/notepad.png?1473769303",
      "name":"Notepad",
      "path":"C:\\Windows\\system32\\notepad.exe",
      "environment": "sandbox"
  }
]
HeaderDescription
X-Frame-ClientIdAPI client identification, client_id.
X-Frame-TimestampTimestamp used in signature calculation.
X-Frame-SignatureCalculated signature.

back to top

Active Session Management

List Active Sessions

Returns list of active sessions for given account. Active sessions are those in status init, open and closing.

GET /v1/accounts/<account_id>/active_sessions
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
  {
    "session_id_hash": "Wr1qgbPa9Pal7E8d",
    "application": "Desktop",
    "remote_ip": "213.240.25.30",
    "starttime": "2017-09-19T01:32:34",
    "state": "open",
    "city": "Belgrade",
    "time_limit": 900,
    "user": "[email protected]",
    "instance_type": "t2.medium",
    "session_type": "sandbox",
    "session_duration": 648
  },
  {
    "session_id_hash": "aRj8g4L01ijYMn8w",
    "application": "Notepad",
    "remote_ip": "213.240.25.30",
    "starttime": "2017-09-19T01:34:45",
    "state": "open",
    "city": "Belgrade",
    "time_limit": 900,
    "user": "[email protected]",
    "instance_type": "t2.medium",
    "session_type": "production",
    "session_duration": 537
  }
]

Get Session

Returns session object for given account and given hashed session ID (as per field session_id_hash in the response of previous endpoint).

GET /v1/accounts/<account_id>/active_sessions/<session_id_hash>
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

{
  "session_id_hash": "aRj8g4L01ijYMn8w",
  "application": "Notepad",
  "remote_ip": "213.240.25.30",
  "starttime": "2017-09-19T01:34:45",
  "state": "open",
  "city": "Belgrade",
  "time_limit": 900,
  "user": "[email protected]",
  "instance_type": "t2.medium",
  "session_type": "production",
  "session_duration": 537
}

Close Session

DELETE request, closes session for given account and given session id hash. Returns empty body with status code 204 in case of success, otherwise will respond with error depending on request data.

DELETE /v1/accounts/<account_id>/active_sessions/<session_id_hash>
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

HTTP/1.1 204 No Content

back to top

Publishing and Application Management

Sandbox Status

Returns Sandbox info for a given account.

GET /v1/accounts/<account_id>/sandbox
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

{
  "id": 1234,
  "status": "running",
  "maintenance": false
}

back to top

Start Sandbox

Invokes starting of sandbox instance, returns HTTP status code 202 in case of success, with empty response body. If sandbox is in ineligible state (if trying to start instance which is not in status stopped), endpoint will return HTTP status code 412 (Precondition failed).

POST /v1/accounts/<account_id>/sandbox/start
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

HTTP/1.1 202 No Content

back to top

Reboot Sandbox

Invokes rebooting of sandbox instance, returns HTTP status code 202 in case of success, with empty response body. If sandbox is in ineligible state (if trying to reboot instance which is not in status running), endpoint will return HTTP status code 412.

POST /v1/accounts/<account_id>/sandbox/reboot
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

HTTP/1.1 202 No Content

back to top

Stop Sandbox

Invokes stopping of sandbox instance, returns HTTP status code 202 in case of success, with empty response body. If sandbox is in ineligible state (if trying to stop instance which is not in status running), endpoint will return HTTP status code 412.

POST /v1/accounts/<account_id>/sandbox/stop
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

HTTP/1.1 202 No Content

back to top

Publish

Invokes publishing: provisioning of workload machine from sandbox. Returns instance of publishing task as a response. Publishing task contains id which can be used to either track publishing status or cancel publishing request.

POST /v1/accounts/<account_id>/sandbox/publish
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

{
  "id": 12345,
  "status": "init",
  "last_change_date": "2016-01-12T14:20:48"
}

back to top

Monitor Publishing Status

Returns instance of publishing task created with Publish request.

GET /v1/accounts/<account_id>/sandbox/publish/<publishing_task_id>
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

{
  "id": 12345,
  "status": "provisioning",
  "last_change_date": "2016-01-12T14:26:29"
}

back to top

Cancel Publishing

Invokes cancelling of publish request. Returns empty response body with status code 202. Request can be cancelled if status of publishing task is not one of the following: "completed", "canceled", "failed", "retired". 

DELETE /v1/accounts/<account_id>/sandbox/publish/<publishing_task_id>
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

HTTP/1.1 202 No Content

back to top

Publishing Tasks

Returns list of all publishing requests created for given account.

GET /v1/accounts/<account_id>/sandbox/publish
HTTP/1.1
Host: api.fra.me
X-Frame-Timestamp: 1475183415
X-Frame-ClientId: cd7bc83b-a9d9-4db5-b3cc-8a144399553a.img.mainframe2.com
X-Frame-Signature: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

[
  {
    "id": 456,
    "status": "completed",
    "last_change_date": "2015-10-29T09:45:12"
    },
  {
    "id": 789,
    "status": "retired",
    "last_change_date": "2016-11-07T11:31:47"
    },
  {
    "id": 12345,
    "status": "provisioning",
    "last_change_date": "2016-01-12T14:28:51"
    }
]

back to top
##API-generated Error Responses
API may not be able to connect to one or more backend services when processing a client's request. In such cases, it will return

  • status code 503 if backend service is temporarily unavailable
  • status code 504 if backend service takes too long to respond (timeout of API gateway's internal client is 10 seconds), with message that corresponds to request method:
Your request timed out, please retry.

Your request timed out. Before sending this request again, please check whether the acted upon resource was successfully completed with a corresponding GET.

Your request timed out. Please make GET request on the resource to check if it has been deleted before retrying.

back to top

Previous Versions

back to top

Updated 2 years ago

Web API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.