HOOPS Server REST API Reference

GET api/help

Description:

Returns a JSON object listing all API endpoints with a brief description

Parameters:

None

Responses:

Status: 200

Description: JSON object listing all API endpoints

Example:

{
  "status": "ok",
  "rest-commands": {
      "help": {
          "description:": "Returns help on REST commands",
          "endpoint": "api/help",
          "http-command": "GET",
          "curl": `${curlExe} http://localhost:${this._config.spawnServerPort}/api/help`
      },
      .
      .
      .
  }
}

POST api/spawn

Description:

Spawn a new instance of a Stream Cache Server (SC-Server)

Top level parameters:

  • class: (optional) Either csr_session (default) or ssr_session. This parameter controls the type of rendering that will be performed by the spawned Stream Cache Server and should be specified at the root level of the request object. This value should correspond to the rendererType value passed into the WebViewer that will connect to this SC Streaming Server.

Optional SC Streaming Server parameters:

Parameters in this category are specified in a params object of the request payload.

  • sessionToken: String that acts as a key to unlock the SC Streaming Server. If specified, this value must match the value of the sessionToken

  • modelSearchDirectories: Array of strings that are paths to additonal directories for the SC Streaming server to search for models. It is reccomended to use abolute paths to directories specified in this manner. These directories will have search precidence over those specified in the HOOPS Server config.

  • model: String that specifies a model to load when the client connects. This value will override the model value passed into the WebViewer that will connect to this SC Streaming Server.

Requests:

Description: Spawn a SSR server

Example:

{
  "class": "ssr_session"
}

Description: Spawn a CSR server with a session token and a model override

Example:

    {
  "class": "csr_session",
  "params": {
    "sessionToken": "my_secret_token",
    "model": "my_model"
  }
}

Responses:

Status: 200

Description: JSON object with details about the newly spawned SC-Server

Example:

{
  "result": "ok",
  "serviceId": "...",
  "endpoints": {
      "ws": "ws://<host>:<port>"
  }
}

Status: 403

Description: Invalid rendering location

Reasons:

  1. The request must have csrEnabled in the server configuration

  2. OR the request must have ssrEnabled with the class parameter set to ssr_session

Status: 503

Description: No ports available

Reason:

  • The HOOPS Server has run out of ports to bind the newly spawned SC-Server

Status: 500

Description: Internal server error catch-all

This endpoint has replaced <service_broker_url>/service from the old HOOPS Server. That endpoint has been deprecated but is backwards compatible with the new HOOPS Server. We strongly recommend you consider updating to the new api/spawn endpoint.

GET api/spawns

Description:

Returns information on all active spawned-servers

Parameters:

None

Responses:

Status: 200

Description: A JSON object with an array of objects containing information about each spawned server

Example:

{
  "timestamp": "1970-01-01T00:00:00.000Z",
  "spawns": [
    {
      "id": "...",
      "state": "'current state of the spawned server'",
      "spawnTime": "1970-01-01T00:00:00.000Z",
      "lastUpdateTime": "1970-01-01T00:00:00.000Z"
    },
    .
    .
    .
  ]
}

POST api/spawn/:spawnId

Description:

This endpoint is intended to be used only by SC-Servers. The endpoint provides an interface to allow an SC-Server to update it’s status with the HOOPS Server. We do not recommend using for any other purpose.

Parameters:

  • spawnId: This path parameter identifies which SC-Server is making the request

  • liveliness: This query parameter provides details on the SC-Servers status update

Responses:

Status: 200

Example:

{
  "result": "ok",
  "serviceId": "...",
  "endpoints": {
      "ws": "ws://<host>:<port>"
  }
}

GET api/status

Description:

Returns status information for the HOOPS Server

Parameters:

None

Responses:

Status: 200

Description: JSON object listing server status information

Example:

{
  "timestamp": "1970-01-01T00:00:00.000Z",
  "status": "ok",
  "config": "'SpawnerConfig of the HOOPS Server'",
  "memory": "'GPU allocation details'",
  "usedSpawnPorts": "'Number of spawns created'",
  "availableSpawnPorts": "'Number of ports still available to the HOOPS Server'",
  "launching": "'Number of spawn with status launching'",
  "ready": "'Number of spawn with status ready'",
  "suspect": "'Number of spawn with status suspect'",
  "disconnected": "'Number of spawn with status disconnected'",
  "nice-killed": "'Number of spawn with status nice-killed'",
  "killed": "'Number of spawn with status killed'",
  "zombie": "'Number of spawn with status zombie'",
  "dead": "'Number of spawn with status dead'"
}

POST api/shutdown

Description:

Initiates shutdown for the HOOPS Server, which includes gracefully shutting down any spawned SC-Servers

Parameters:

None

Responses:

Status: 200

Example:

{
  "status": "ok",
  "message": "Server is shutting down"
}

POST api/gc

Description:

Forces NodeJS to run the garbage collector

Parameters:

None

Responses:

Status: 200

Example:

{
  "status": "ok",
  "preGcMemory": {
    "rss": "...",
    "heapTotal": "...",
    "heapUsers": "...",
    "external": "...",
  },
  "postGcMemory": {
    "rss": "...",
    "heapTotal": "...",
    "heapUsers": "...",
    "external": "...",
  },
  "delta": {
    "rss": "...",
    "heapTotal": "...",
    "heapUsers": "...",
    "external": "...",
  },
}