HostManagement

The system resource based on the HostManagement type is used to show APS resources representing the service nodes (also known as hosts) registered in the system. It implements the APS core Resource type.

In this document:

GraphViz

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "HostManagement",
  "id": "http://www.parallels.com/pa/pa-core-services/host-management/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "getServiceNodes": {
      "path": "hosts",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "customerApsId": {
          "kind": "query",
          "type": "string"
        },
        "platform": {
          "kind": "query",
          "type": "string"
        },
        "ipv4": {
          "kind": "query",
          "type": "string"
        },
        "ipv6": {
          "kind": "query",
          "type": "string"
        },
        "ipPoolPurpose": {
          "kind": "query",
          "type": "string"
        },
        "hostAttribute": {
          "kind": "query",
          "type": "array"
        },
        "capacity": {
          "kind": "query",
          "type": "array"
        },
        "throwException": {
          "kind": "query",
          "type": "boolean"
        }
      }
    }
  }
}

The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:

POST  /aps/2/services/host-manager/<operation-path>?<query-params>

{/*<body params>*/}

In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.

Custom Operations

OPERATION

VERB

PATH

RETURNS

Description

getServiceNodes

GET

/hosts

Array of Host

The getServiceNodes operation accepts a list of service node parameters (each parameter is optional) and returns an array of service nodes meeting that set of input parameters.

getServiceNodes

HTTP Request

GET /aps/2/services/host-manager/hosts

Description

The getServiceNodes operation accepts a list of service node parameters (each parameter is optional) and returns an array of service nodes meeting that set of input parameters.

Parameters

PARAMETER

TYPE

DESCRIPTION

customerApsId

String

APS ID of a customer to find out the service nodes that the customer’s vendor ownes.

platform

String

OS family, either “Linux” or “Windows” (default is “Linux”).

ipv4

String

IPv4 address of the node.

ipv6

String

IPv6 address of the node.

ipPoolPurpose

String

A list of purposes used to identify if the IP pool attached to an interface of the service node may be used for virtual hosts the application needs to provision on the node. An IP pool can be used to assign IP addresses for one or several of the following purposes: “COMMON.BRANDING” (in the provider control panel - “Branding configuration”) - the FrontNet interface of brand hosts of the platform control panel. “COMMON.INTERNAL” (in the provider control panel - “Infrastructure configuration”) - the BackNet (exclusive IP addresses) or FrontNet (shared IP addresses) interface of virtual hosts. “DEDICATED.HOSTING” (in the provider control panel - “Dedicated hosting”) - FrontNet interface of dedicated hosts. “SHARED.HOSTING” (in the provider control panel - “Shared hosting”) - FrontNet interface (exclusive IP addresses) of virtual hosts.

hostAttribute

Array

A list of one or more provisioning attributes assigned to the service node. The service node can provision a new virtual host only if the list of provisioning attributes on the new host is a subset of the provisioning attributes on the service node. The names of the attributes are arbitrary.

capacity

Array

A list of capacity objects based on the Capacity APS type.

throwException

Boolean

If true, the method throws an exception on some errors, otherwise it returns an empty list. The following example illustrates a request for a list of service nodes that are assigned the “MainStreamHosting” provisioning attribute: GET /aps/2/resources/f6d44eac-b889-4680-a187-6cd340795b12/hosts?hostAttribute=MainStreamHosting

Returns

Array of Host

Examples

Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.

Host