EaaSI API

Emulation-as-a-Service exposes a number of RESTful API endpoints users can employ with an API client (including curl or any other HTTP request tooling) to get some descriptive and technical information on the resources present in an EaaSI installation.

Authentication and Access Tokens

Users with an account on an EaaSI server can query the API based on their unique user context (for example, to receive metadata about Private Environments or imported Software resources) by obtaining an access token from EaaSI’s Keycloak authentication module.

Note

If no access token/user context is provided, GET requests to the public API may still return metadata on a server’s published/public resources (Public Environments)

Users with an EaaSI account can acquire an access token from their server by sending a POST request to https://[eaasi.domain]/auth/realms/master/protocol/openid-connect/token, for example:

$ curl --request POST \
--url https://[eaasi.domain]/auth/realms/master/protocol/openid-connect/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data client_id=eaas \
--data grant_type=password \
--data username=[user] \
--data password=[password]

Being sure to replace all information in [] with the appropriate values/credentials. Tokens are valid for an hour by default, after which they must be regenerated or refreshed.

A valid request should receive an OAuth 2.0 access token response. The received access_token property value can then be provided in the header of subsequent requests to the EaaS API, for example:

curl --request GET \
--url 'https://[eaasi.domain]/emil/environment-repository/environments' \
--header 'Authorization: Bearer [access_token]' \
--header 'accept: application/json'

Public API

All public EaaS API endpoints are located under the base URL: https://[eaasi.domain]/emil

Environments

GET /environment-repository/environments

Retrieves a list of all available Environments in the server

Request Headers:

• Accept – Should define response content type as application/json

• Authorization – optional OAuth token to authenticate (necessary to retrieve Private Environments)

Query Parameters:

• detailed (boolean) – If set to “true”, can be used to display all metadata associated with each Environment rather than an overview (see environment-repository/environments/[envId] endpoint documentation below for full details included; “false” by default)

• localOnly (boolean) – If set to “false”, returns metadata associated with Public Environments visible but not Saved Locally to the server (“true” by default)

Status Codes:

• 200 OK – An array of Environments

Response JSON Object:

• envId (string) – Unique ID (UUID) for an Environment resource

• title (string) – Human-readable name for an Environment resource

• archive (string) – Indicates the Environment’s storage archive, one of three options depending on its Network Status (returns “remote” for Public, “public” for Saved Locally, “default” for Private)

• owner (string) – Indicates user account that owns the Environment resource (either returns “shared” for Public or Saved Locally, or a UUID for provided user account’s Private Environments)

• objectId (string) – If Environment is a Content Environment, returns the UUID of the associated Content object

• objectArchive (string) – If Environment is a Content Environment, returns the UUID of the user archive associated with that Content (should be the same as owner UUID)

• envType (string) – Returns “object” if Environment is a Content Environment, returns “base” for all others

• timestamp (string) – ISO 8601 full-time timestamp for when the Environment was created

• description (string) – The most recent description of the Environment from its History (displayed during running Emulation Access sessions)

• linuxRuntime (boolean) – Indicates if the Environment is a Linux runtime appropriate for importing and running containers (an EaaS feature not yet implemented in EaaSI nodes)

• networkEnabled (boolean) – Indicates if the Environment is capable of networking with the live internet or other Environments (the latter is an EaaS feature not yet implemented in EaaSI nodes)

• internetEnabled (boolean) – Indicates if the Environment is allowed to connect to the live internet (can only be “true” if networkEnabled is also “true”)

• serviceContainer (boolean) – Indicates if the Environment represents a container service (an EaaS feature not yet implemented in EaaSI nodes)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
  "envId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": "Windows 98 + Borland Quattro Pro 5.0",
  "archive": "default",
  "owner": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "envType": "base",
  "timestamp": "2022-04-27T17:45:45.922581Z",
  "description": "installed to C: drive",
  "linuxRuntime": false,
  "networkEnabled": true,
  "internetEnabled": true,
  "serviceContainer": false
  },
  {
  "envId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": "The Would-Be Gentleman",
  "archive": "default",
  "owner": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "objectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "objectArchive": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "envType": "object",
  "timestamp": "2022-03-17T15:18:56.917042Z",
  "description": "unstuffed floppy image and copied contents to MacintoshHD",
  "linuxRuntime": false,
  "networkEnabled": false,
  "internetEnabled": false,
  "serviceContainer": false
  }
]

GET /environment-repository/environments/[envId]

Retrieves a detailed record of a single Environment, as defined by a provided UUID

Request Headers:

• Accept – Should define response content type as application/json

• Authorization – optional OAuth token to authenticate (necessary to retrieve Private Environments)

Status Codes:

• 200 OK – A single Environment JSON object

• 400 Bad Request – No Environment with the specified UUID found

Response JSON Object:

• networking (object) – a nested JSON object literal describing the Environment’s emulated networking capabilities

• enableInternet (nested,boolean) – Indicates if the Environment is allowed to connect to the live internet (can only be “true” if networkEnabled is also “true”)

• serverMode (nested,boolean) – EaaS feature not yet implemented in EaaSI nodes

• localServerMode (nested,boolean) – EaaS feature not yet implemented in EaaSI nodes

• enableSocks (nested,boolean) – EaaS feature not yet implemented in EaaSI nodes

• connectEnvs (nested,boolean) – EaaS feature not yet implemented in EaaSI nodes

• parentEnvId (string) – If the Environment is a derivative, this references the unique ID (UUID) of the base Environment this derivative was directly saved from

• envId (string) – Unique ID (UUID) for the Environment resource

• title (string) – Human-readable name for the Environment resource

• description (string) – The most recent description of the Environment from its History (displayed during running Emulation Access sessions)

• emulator (string) – JavaBeans bean name for the emulator used by this Environment resource

• enableRelativeMouse (boolean) – When “true”, enables the “Relative Mouse (Pointerlock)” setting (see: Environment Details)

• enablePrinting (boolean) – When “true”, enables the “Environment Can Print” setting (see: Environment Details)

• shutdownByOs (boolean) – When “true”, enables the “Requires Clean Shutdown” setting (see: Environment Details)

• timeContext (string) –

• canProcessAdditionalFiles (boolean) – EaaS feature not yet implemented in EaaSI nodes

• archive (string) – Indicates the Environment’s storage archive, one of three options depending on its Network Status (returns “remote” for Public, “public” for Saved Locally, “default” for Private)

• xpraEncoding (string) – When useXpra is set to “true”, this string determines the type of image encoding used by the Xpra display server and client (“jpeg” by default)

• owner (string) – Indicates user account that owns the Environment resource (either returns “shared” for Public or Saved Locally, or a UUID for provided user account’s Private Environments)

• envType (string) – Returns “object” if Environment is a Content Environment, returns “base” for all others

• revisions (array) – If the selected Environment is a derivative, a sub-array of the previous revisions in the Environment’s History (listed from most recent to oldest revisions)

• id (string) – envId for the previous Environment in the derivative chain

• text (nested,string) – The description for the previous Environment in the derivative chain

• archive – The archive for the previous Environment in the derivative chain

• installedSoftwareIds (array) – A sub-array of any Software resources associated with this Environment. Could include an operating system installer if the Environment is a base or other associated Software resources if the Environment is a derivative

• id – The id of any associated Software resource

• label (string) – The human-readable name of any associated Software resource

• archive – The archiveId for the storage archive where the associated Software resource is kept

• nativeConfig (string) – Arbitrary string/flags added to configured emulator’s default when Environment is run (see: Emulator Configuration)

• useXpra (boolean) – When “true”, enables the “XPRA Video” setting (see: Environment Details)

• useWebRTC (boolean) – When “true”, enables the “WebRTC Audio” setting (see: Environment Details)

• containerName (string) – Name for the Docker container matching the specified emulator bean

• drives (array) – A sub-array of JSON objects, each represeting the emulated drives available for this Environment

• data (nested,string) – If an object or environment image is bound to this drive, its unique ID (UUID) will be indicated in this field (i.e. system drives or a Content Environment)

• iface (nested,string) – Computer storage standard/interface used by the emulated drive (options are “ide” or “floppy”)

• bus (nested,string) – Computer bus address number used by the emulated drive

• unit (nested,string) – Computer storage bus unit address number used by the emulated drive

• type (nested,string) – Corresponding Physical Media type for the emulated drive (allows which type of resource objects can be loaded into this drive; accepted values are “floppy”, “cdrom”, or “disk”)

• filesystem (nested,string) – Indicates the filesystem types accepted by the emulated drive (e.g. “ISO” for “cdrom” drives or “fat12” for “floppy”)

• boot (nested,boolean) – Communicates to the emulator (if possible) that this drive should be indicated as the system/boot drive (only one drive in the Environment configuration should be marked “true”, otherwise behavior will be unpredictable)

• plugged (nested,boolean) –

• timestamp (string) – ISO 8601 full-time timestamp for when the Environment was created

• linuxRuntime (boolean) – Indicates if the Environment is a Linux runtime appropriate for importing and running containers (EaaS feature not yet implemented in EaaSI nodes)

• isServiceContainer (boolean) – Indicates if the Environment represents a container service (EaaS feature not yet implemented in EaaSI nodes)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"networking": {
  "enableInternet": false,
  "serverMode": false,
  "localServerMode": false,
  "enableSocks": false,
  "connectEnvs": false
  },
"parentEnvId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"envId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"title": "Windows 98 + Borland Quattro Pro 5.0",
"description": "installed to C: drive",
"emulator": "Qemu",
"enableRelativeMouse": false,
"enablePrinting": true,
"shutdownByOs": false,
"timeContext": "1628524787526",
"canProcessAdditionalFiles": false,
"archive": "default",
"xpraEncoding": "jpeg",
"owner": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"envType": "base",
"revisions": [
    {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "text": "removed daylight savings time pop-up",
    "archive": "default"
    },
    {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "text": "fixed Plug n Play BIOS warning, rebooted to add Soundblaster card",
    "archive": "public"
    },
    {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.xml",
    "text": "n.a.",
    "archive": "public"
    }
  ],
"installedSoftwareIds": [
    {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "label": "Windows98SE",
    "archive": "zero conf"
    },
    {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "label": "Borland Quattro Pro 5.0",
    "archive": "zero conf"
    }
  ],
"nativeConfig": "-usb -usbdevice tablet -vga cirrus -soundhw sb16 -net nic,model=pcnet",
"useXpra": false,
"useWebRTC": false,
"containerName": "qemu-system",
"drives": [
    {
    "data": "binding://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "iface": "ide",
    "bus": "0",
    "unit": "0",
    "type": "disk",
    "boot": true,
    "plugged": true
    },
    {
    "iface": "floppy",
    "bus": "0",
    "unit": "0",
    "type": "floppy",
    "filesystem": "fat12",
    "boot": false,
    "plugged": false
    },
    {
    "iface": "ide",
    "bus": "0",
    "unit": "1",
    "type": "cdrom",
    "filesystem": "ISO",
    "boot": false,
    "plugged": false
    }
  ],
"timestamp": "2022-04-27T17:45:45.922581Z",
"linuxRuntime": false,
"isServiceContainer": false
}

Software

GET /software-repository/descriptions

Retrieves a lightweight list of Software resources

Request Headers:

• Accept – Should define response content type as application/json

• Authorization – OAuth token to authenticate (necessary to retrieve Private Software resources)

Status Codes:

• 200 OK – An array of Software

Response JSON Object:

• id (string) – Unique ID (UUID) for this Software resource

• label (string) – Human-readable name for a Software resource

• isPublic (boolean) – Indicates if the Software resource has been published (publishing Software resources has not yet been properly implemented in EaaSI; this value should be “false”)

• archiveId (string) – Name for the storage archive where the Software object is kept; should be “zero conf” for all private Software resources

• isOperatingSystem (boolean) – Indicates if the Software resource has been identified as an operating system installer during resource import (available via Demo UI but not yet re-incorporated into EaaSI UI import process; should be “false” but certain legacy objects may display “true”)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "Microsoft Money 95",
  "isPublic": false,
  "archiveId": "zero conf",
  "isOperatingSystem": false
  },
  {
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "Advanced_DB_Master_3.0",
  "isPublic": false,
  "archiveId": "zero conf",
  "isOperatingSystem": false
  }
]

GET /software-repository/descriptions/[id]

Retrieves description for a single Software resource, as defined by provided UUID

Request Headers:

• Accept – Should define response content type as application/json

• Authorization – OAuth token to authenticate (necessary to retrieve Private Software resources)

Status Codes:

• 200 OK – A single Software JSON object

• 500 Internal Server Error – No Software object with the specified UUID found

Response JSON Object:

• id (string) – Unique ID (UUID) for this Software resource

• label (string) – Human-readable name for this Software resource

• isPublic (boolean) – Indicates if this Software resource has been published (publishing Software resources has not yet been properly implemented in EaaSI; this value should be “false”)

• archiveId (string) – Name for the storage archive where the Software object is kept; should be “zero conf” for all private Software resources

• isOperatingSystem (boolean) – Indicates if the Software resource has been identified as an operating system installer during resource import (available via Demo UI but not yet re-incorporated into EaaSI UI import process; should be “false” but certain legacy objects may display “true”)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  {
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "Microsoft Money 95",
  "isPublic": false,
  "archiveId": "zero conf",
  "isOperatingSystem": false
  }

GET /software-repository/packages

Retrieves a more detailed array of Software objects, including associated file formats

Request Headers:

• Accept – Should define response content type as application/json

• Authorization – OAuth token to authenticate (necessary to retrieve Private Software resources)

Status Codes:

• 200 OK – An array of Software

Response JSON Object:

• id (string) – Unique ID (UUID) for this Software resource

• objectId (string) – Unique ID (UUID) for this Software object (should be same as id)

• label (string) – Human-readable name for a Software resource

• licenseInformation (string) – Open field for defining any relevant software license information

• allowedInstances (integer) – Defines how many concurrent emulation sessions may be run with this Software object mounted (default is “-1”, indicating unlimited sessions)

• nativeFMTs (array) – An array of file format PUIDs that have been manually assigned with this Software object as formats that can be natively rendered in Environments associated with this Software resource (see uvi)

• importFMTs (array) – An array of file format PUIDs that have been manually assigned with this Software object as formats that can specifically be imported in Environments associated with this Software resource (primarily experimental, for investigating automated migration)

• exportFMTs (array) – An array of file format PUIDs that have been manually assigned with this Software object as formats that can specifically be exported from Environments associated with this Software resource (primarily experimental, for investigating automated migration)

• archiveId (string) – Name for the storage archive where the Software object is kept; should be “zero conf” for all private Software resources

• isPublic (boolean) – Indicates if the Software resource has been published (publishing Software resources has not yet been properly implemented in EaaSI; this value should be “false”)

• isOperatingSystem (boolean) – Indicates if the Software resource has been identified as an operating system installer during resource import (available via Demo UI but not yet re-incorporated into EaaSI UI import process; should be “false” but certain legacy objects may display “true”)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "objectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "Microsoft Money 95",
  "licenseInformation": "Proprietary commercial",
  "allowedInstances": 1,
  "nativeFMTs": ["fmt/38", "fmt/138", "fmt/57"],
  "importFMTs": ["x-fmt/18", " x-fmt/13"],
  "exportFMTs": ["x-fmt/18", "fmt/15"],
  "archiveId": "zero conf",
  "isPublic": false,
  "isOperatingSystem": false
  },
  {
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "objectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "Advanced_DB_Master_3.0",
  "licenseInformation": "License key: xxx-xxxxx",
  "allowedInstances": -1,
  "nativeFMTs": ["fmt/38", "fmt/138", "fmt/57"],
  "importFMTs": ["x-fmt/18", " x-fmt/13"],
  "exportFMTs": ["x-fmt/18", "fmt/15"],
  "archiveId": "zero conf",
  "isPublic": false,
  "isOperatingSystem": false
  }
]

GET /software-repository/packages/[id]

Retrieves a more detailed view of a single Software resource, as defined by provided UUID

Request Headers:

• Accept – Should define response content type as application/json

• Authorization – OAuth token to authenticate (necessary to retrieve Private Software resources)

Status Codes:

• 200 OK – A single Software JSON object

• 500 Internal Server Error – No Software object with the specified UUID found

Response JSON Object:

• id (string) – Unique ID (UUID) for this Software resource

• objectId (string) – Unique ID (UUID) for this Software object (should be same as id)

• label (string) – Human-readable name for this Software resource

• licenseInformation (string) – Open field for defining any relevant software license information

• allowedInstances (integer) – Defines how many concurrent emulation sessions may be run with this Software object mounted (default is “-1”, indicating unlimited sessions)

• nativeFMTs (array) – An array of file format PUIDs that have been manually assigned with this Software object as formats that can be natively rendered in Environments associated with this Software resource (see uvi)

• importFMTs (array) – An array of file format PUIDs that have been manually assigned with this Software object as formats that can specifically be imported in Environments associated with this Software resource (primarily experimental, for investigating automated migration)

• exportFMTs (array) – An array of file format PUIDs that have been manually assigned with this Software object as formats that can specifically be exported from Environments associated with this Software resource (primarily experimental, for investigating automated migration)

• archiveId (string) – Name for the storage archive where the Software object is kept; should be “zero conf” for all private Software resources

• isPublic (boolean) – Indicates if the Software resource has been published (publishing Software resources has not yet been properly implemented in EaaSI; this value should be “false”)

• isOperatingSystem (boolean) – Indicates if the Software resource has been identified as an operating system installer during resource import (available via Demo UI but not yet re-incorporated into EaaSI UI import process; should be “false” but certain legacy objects may display “true”)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  {
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "objectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "Microsoft Money 95",
  "licenseInformation": "Proprietary commercial",
  "allowedInstances": 1,
  "nativeFMTs": ["fmt/38", "fmt/138", "fmt/57"],
  "importFMTs": ["x-fmt/18", " x-fmt/13"],
  "exportFMTs": ["x-fmt/18", "fmt/15"],
  "archiveId": "zero conf",
  "isPublic": false,
  "isOperatingSystem": false
  }