Control hosts

Edit online

Description

URL

scheme://domain:port/platform/ws/hosts/open

scheme://domain:port/platform/ws/hosts/close

Purpose

Controls the specified hosts, or hosts in the specified host groups.

Valid actions:

  • open: Opens the selected hosts. A host must be open to accept jobs.
  • close: Closes the selected hosts. A closed host cannot accept any new job, but jobs already dispatched to the host are not affected.

HTTP Method

 POST

Parameters

 Name Description
  names

Mandatory. Take action on the specified host, or take action on hosts belonging to the specified host group. To specify multiple host names or host groups, separate with a comma(,). For example: hostA,hostB.

Use the keyword all to take action on all hosts in the cluster.

To get a list of hosts, use the API /platform/ws/hosts.

To get a list of hosts, use the API /platform/ws/hostgroups.

Request

Request Request Information
Method POST
Request-URI

http://<hostname>:<port>/platform/ws/hosts/open

http://<hostname>:<port>/platform/ws/hosts/close
Request-Header Name Value
Accept application/xml or application/json
Message-Body names =%s

Response

Response Response Information
Response Code
  • 303 See Other: Action performed successfully. Get the URI for details.
  • 403 Forbidden: Access restricted by role-based access control permissions.
  • 404 Not Found: No hosts that match the specified criteria were found.
  • 500 Internal Server Error: Exception occurred.
Response-Header Name Value

Content-Type

Application/xml or application/json

Location (only if response code is 303)

A URI that gets the hosts or host groups on which the operation was performed.

Message-body

 Success Message

If successful, returns the URI for hosts and host groups on which the specified operation was successful.
Failure Message

If not successful, returns an error message.

For additional information, refer to the schema file ./schemas/hosts/error.xsd.

<error>
  <message>
     %s
  </message>
</error>

Example: Close hosts hostA and hostB

# Request
POST /platform/ws/hosts/close HTTP/1.1
Host: www.example.org
Authorization: Basic d2VsaXU6bGV0bWVpbg==
names= hostA,hostB
# Response
303 See Other
Location: http://www.example.org/platfrom/ws/hosts?names= hostA,hostB

Example: Close all hosts in the cluster

# Request
POST /platform/ws/hosts/close HTTP/1.1
Host: www.example.org
Authorization: Basic d2VsaXU6bGV0bWVpbg==
names=all
# Response
303 See Other
Location: http://www.example.org/platfrom/ws/hosts?names=all

Related APIs

To get a list of hosts, use the API /platform/ws/hosts.

To get a list of host groups, use the API /platform/ws/hostgroups.