Cloudify REST API V3

Basic usage

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3/<endpoint>"

# Using ClodifyClient
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    username='<manager-username>',
    password='<manager-password>',
    tenant='<manager-tenant>')

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager-ip>/api/v3/<endpoint>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers)
response.json()

Welcome to Cloudify’s REST API Documentation!

The base URI for the v3 REST API is: /api/v3.

Starting from Cloudify 4.0.0, all communication to the server requires:

Authentication using user credentials.
Tenant name, representing the scope of the request.

Every Cloudify Manager has a default tenant, called default_tenant. The default_tenant tenant is created during bootstrap.

In addition to the default_tenant, every Cloudify Manager includes a bootstrap Admin. The bootstrap Admin is the Admin user that created during the bootstrap.

In addition to the user credentials, every request must also specify a tenant in the header.

In the case of using the Cloudify community edition or if you have not created any new tenant, you can use the default_tenant as the tenant for the request.

Parameters

<manager-ip>: Replace with the IP of your Cloudify Manager
<manager-username>: Replace with a username for the Cloudify Manager instance username
<manager-password>: Replace with the password for the user specified in
<manager-tenant>: Replace with the tenant on which to perform the request
<manager-token>: Replace with a token obtained using the tokens endpoint (see the athentication section)

Response Fields Filtering (Projection)

Request Example (receive only the id and created_at fields)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-api>/api/v3/blueprints?_include=id,created_at"

# Using ClodifyClient
blueprints = client.blueprints.list(_include=['id','created_at'])
for blueprint in blueprints:
  print blueprint

# Using requests
url = 'http://<manager-ip>/api/v3/blueprints'
querystring = {'_include': 'id,created_at'}
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "created_at": "2017-04-17T12:12:36.626Z",
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1
    }
  }
}

You can choose to have only specific fields in the response by using the _include query parameter.

The parameter value is a comma separated list of fields to include in the response, e.g. _include=field1,field2,field3

Note that specified field names must be part of the resource schema, otherwise an error is raised.

Query Filtering (Selection)

Request Example (requesting only blueprints which id is _myblueprint1 or _myblueprint2)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3/blueprints?_include=id,created_at&id=my-blueprint-1&id=my-blueprint-2"

# Using ClodifyClient
blueprints = client.blueprints.list(
    _include=['id','created_at'],
    id=['my-blueprint-1', 'my-blueprint-2'],
)
for blueprint in blueprints:
    print blueprint

# Using requests
url = "http://<manager-ip>/api/v2.1/blueprints"
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,created_at',
    'id': ['my-blueprint-1', 'my-blueprint-2'],
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "created_at": "2017-04-17T12:34:52.911Z",
      "id": "my-blueprint-1"
    },
    {
      "created_at": "2017-04-17T12:34:57.256Z",
      "id": "my-blueprint-2"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 2
    }
  }
}

You can make your query more specific by using filters.

Filters are query parameters where the key is a field name and the value is a field value, e.g. id=my-specific-id

Filters also accept multiple values (OR) by using multiple parameters of the same key, e.g. id=my-specific-id&id=another-id

Sorting

Request Example #1 (sort deployments by id descending)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager_ip>/api/v3/deployments?_include=id,blueprint_id&_sort=-id"

# Using CloudifyClient
deployments = client.deployments.list(
    _include=['id', 'blueprint_id'],
    _sort='-id',
)
for deployment in deployments:
    print deployment

# Using requests
url = 'http://<manager-ip>/api/v3/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,blueprint_id',
    '_sort': '-id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #1

{
  "items": [
    {
      "id": "hello1",
      "blueprint_id": "hello-world"
    },
    {
      "id": "dep4",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep3",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep2",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep1",
      "blueprint_id": "my-blueprint-1"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 5,
      "offset": 0,
      "size": 5
    }
  }
}

Request Example #2 (sort deployments by blueprint_id ascending and id descending)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager_ip>/api/v3/deployments?_include=id,blueprint_id&_sort=blueprint_id&_sort=-id"

# Using CloudifyClient
deployments = client.deployments.list(
    _include=['id', 'blueprint_id'],
    _sort=['blueprint_id', '-id'],
)
for deployment in deployments:
    print deployment

# Using requests
url = 'http://<manager-ip>/api/v3/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_include': 'id,blueprint_id',
    '_sort': ['blueprint_id', '-id'],
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #2

{
  "items": [
    {
      "id": "hello1",
      "blueprint_id": "hello-world"
    },
    {
      "id": "dep3",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep1",
      "blueprint_id": "my-blueprint-1"
    },
    {
      "id": "dep4",
      "blueprint_id": "my-blueprint-2"
    },
    {
      "id": "dep2",
      "blueprint_id": "my-blueprint-2"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 5,
      "offset": 0,
      "size": 5
    }
  }
}

Sort resources by using the _sort query parameter, e.g. _sort=id

The default sort order is ascending; to make it descending, prefix the field with a minus sign, e.g. _sort=-id (example #1)

Sorting also works on multiple fields by using multiple _sort parameters, where the sort sequence corresponds to the order of _sort parameters in the request (example #2).

Pagination

Request Example (skip 1 resource, get size of 4)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/events?_size=4&_offset=1&_include=timestamp"

# Using CloudifyClient
events = client.events.list(
    _size=4,
    _offset=1,
    _include=['timestamp'],
)

# Using requests
url = 'http://<manager-ip>/api/v3/events'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    '_size': '4',
    '_offset': '1',
    '_include':'timestamp',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "timestamp": "2017-04-17T13:53:22.570Z"
    },
    {
      "timestamp": "2017-04-17T13:53:10.558Z"
    },
    {
      "timestamp": "2017-04-17T13:53:09.799Z"
    },
    {
      "timestamp": "2017-04-17T13:52:54.549Z"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 20,
      "offset": 1,
      "size": 4
    }
  }
}

If the response includes too many items for the client to handle at once, use pagination to get only a subset of the results, defined by two parameters:

_size (default: 10000) the max size of the result subset to receive.
_offset (default: 0) the number of resources to skip, i.e. _offset=1 means you skip the first resource.

* both parameters are optional.

The response metadata returns the requested parameters, and a total field which indicates the size of the full set.

Authentication

Authentication headers should be added to every request sent to a secured manager.
Any header can be used, as long as it’s support by one of the manager’s authentication providers. The default manager configuration supports basic HTTP authentication (examples #1, #2) and tokens (example #3).
Valid credentials do not affect the returned response, but invalid credentials return a “User Unauthorized” error.

Request Example #1 (Get the server’s status, authenticate with username and password)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "http://<manager-ip>/api/v3/status?_include=status"

# Using CloudifyClient
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3/status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'status'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example #1

{
  "status": "running"
}

Request Example #2 (Get a token, authenticate with username and password)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-pasword> \
    "<manager-ip>/api/v3/tokens"

# Using CloudifyClient
client.tokens.get()

# Using requests
url = 'http://<manager-ip>/api/v3/tokens'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example #2

{
  "role": "admin",
  "value": "WyIwIiwiMzE0OTNmNWFjOTE1MzdhM2IyZWM4NTFhYWY4NzU0NWEiXQ.C9Z82w.dlVgLkkyeWZgZP06xMxe8Omht90"
}

Request Example #3 (Get all the blueprints, authenticate with a token)

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    --header "Authentication-Token: <manager-token>" \
    "http://<manager-ip>/api/v3/blueprints?_include=id"

# Using CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    tenant='<manager-tenant>',
    token='<manager-token>',
)
blueprints = client.blueprints.list(_include=['id'])
for blueprint in blueprints:
    print blueprint

# Using requests
url = 'http://<manager-ip>/api/v3/blueprints'
headers = {
    'Tenant': '<manager-tenant>',
    'Autentication-Token': '<manage-token>',
}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    headers=headers,
    params=querystring,
)
response.json()

Response Example #3

{
  "items": [
    {
      "id": "my-blueprint-1"
    },
    {
      "id": "my-blueprint-2"
    },
    {
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

Blueprints

The Blueprint Resource

Attributes:

Attribute	Type	Description
`created_at`	datetime	The time the blueprint was uploaded to the manager.
`description`	string	The blueprint’s description.
`id`	string	A unique identifier for the blueprint.
`main_file_name`	string	The blueprint’s main file name.
`plan`	dict	The parsed result of the blueprint.
`updated_at`	datetime	The last time the blueprint was updated.

Get Blueprint

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/blueprints?id=<blueprint-id>&_include=id"

# Using CloudifyClient
client.blueprints.get(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/api/v3/blueprints'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'id': '<blueprint-id>',
    '_include': 'id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello-world"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 1
    }
  }
}

GET "{manager-ip}/api/v3/blueprints?id={blueprint-id}"

Gets a specific blueprint.

URI Parameters

blueprint-id: The id of the blueprint to retrieve.

Response

A Blueprint resource.

Upload Blueprint

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/blueprints/<blueprint-id>?application_file_name=<blueprint-id>.yaml&blueprint_archive_url=https://url/to/archive/master.zip"

# Using CloudifyClient
client.blueprints._upload(
    blueprint_id='<blueprint-id>',
    archive_location='https://url/to/archive/master.zip',
    application_file_name='<blueprint-id>.yaml',
)

# Using requests
url = 'http://<manager-ip>/api/v3/blueprints/<blueprint-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'application_file_name': '<blueprint-id>.yaml',
    'blueprint_archive_url': 'https://url/to/archive/master.zip',
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "main_file_name": "singlehost-blueprint.yaml",
  "description": "This blueprint installs a simple web server on the manager VM using Cloudify's script plugin.\n",
  "tenant_name": "default_tenant",
  "created_at": "2017-04-19T10:56:06.267Z",
  "updated_at": "2017-04-19T10:56:06.267Z",
  "created_by": "admin",
  "private_resource": false,
  "plan": {
    ...
  },
  "id": "hello-world"
}

PUT "{manager-ip}/api/v3/blueprints/{blueprint-id}?application_file_name={blueprint-id}.yaml&blueprint_archive_url=https://url/to/archive/master.zip"

Uploads a blueprint to Cloudify’s manager. The call expects an “application/octet-stream” content type where the content is a zip/tar.gz/bz2 archive. It is possible to upload a blueprint from a URL by specifying the URL in the blueprint_archive_url request body property.

URI Parameters

blueprint-id: The id of the uploaded blueprint.

Request Body

Property	Type	Description
`application_file_name`	string	The main blueprint file name in the blueprint’s archive.
`blueprint_archive_url`	string	A URL the blueprint to be uploaded should be downloaded from by the manager.

Response

A Blueprint resource.

List Blueprints

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3/blueprints?_include=id"

# Using CloudifyClient
blueprints = client.blueprints.list(_include=['id'])
for blueprint in blueprints:
    print blueprint

# Using requests
url = "http://<manager-ip>/api/v3/blueprints"
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello-world"
    },
    {
      "id": "hello-world-2"
    },
    {
      "id": "hello-world-3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 3
    }
  }
}

GET "{manager-ip}/api/v3/blueprints"

Lists all blueprints.

Response

Field	Type	Description
`items`	list	A list of `Blueprint` resources.

Delete Blueprint

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/blueprints/<blueprint-id>"

# Using CloudifyClient
client.blueprints.delete(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/ap/v3/blueprints/<blueprint-id>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "tenant_name": "default_tenant",
  "created_at": "2017-04-19T13:35:13.971Z",
  "updated_at": "2017-04-19T13:35:13.971Z",
  "created_by": "admin",
  "private_resource": false,
  "plan": {
    ...
  },
  "id": "hello-world"
}

DELETE "{manager-ip}/api/v3/blueprints/{blueprint-id}"

Deletes a specific blueprint.

URI Parameters

blueprint-id: The id of the blueprint to delete.

Response

A Blueprint resource.

Download Blueprint

Downloads a specific blueprint as an archive.

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/blueprints/<blueprint-id>/archive" > <blueprint-archive-filename>.tar.gz

# Using CloudifyClient
client.blueprints.download(blueprint_id='<blueprint-id>')

# Using requests
url = 'http://<manager-ip>/api/v3/blueprints/<blueprint-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<blueprint-archive-filename>.tar.gz', 'wb') as blueprint_archive:
    blueprint_archive.write(response.content)

GET "{manager-ip}/api/v3/blueprints/{blueprint-id}/archive"

URI Parameters

blueprint-id: The id of the blueprint to download.

Response

The blueprint as an archive using an application/octet-stream content type.

Cluster

The ClusterState Resource

# Include this code when using the Cloudify Python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>')

The ClusterState resource represents the current state of a Cloudify Manager cluster.

Attributes:

Attribute	Type	Description
`consul`	dict	Detailed state of the consul cluster being part of the manager infrastructure.
`error`	string	Description of a fatal error that occured during cluster configuration or operation, if any.
`initialized`	boolean	Whether this node is part of a cluster.
`logs`	list	Logs of the cluster operations on the current node.

Get Cluster State

Request Example

$ curl -u user:password "http://<manager-ip>/api/v3/cluster"

client.cluster.status()

Response Example (cluster not initialized)

{
    "initialized": false
}

Response Example

{
    "initialized": true,
    "consul": {
        "leader": "172.20.0.3:8300"
    },
    "error": null,
    "logs": [
        {
            "message": "HA Cluster configuration complete",
            "timestamp": 1485778546965628,
            "cursor": "opaque cursor value"
        }
    ]
}

GET "{manager-ip}/api/v3/cluster"

Retrieves the current cluster state. The logs and error fields are hidden by default, but can be added to the response if specified using the _include query parameter.

Response

A ClusterState resource.

URI Parameters

since: When including logs, fetch only logs that are more recent than this cursor value.

Put Cluster State

Request Example

# starting a cluster
client.cluster.start(
    host_ip='172.20.0.2',
    node_name='manager',
)
# joining a cluster
client.cluster.join(
    host_ip='172.20.0.3',
    node_name='another-manager',
    credentials='<REDACTED>'
)

$ curl -X PUT -H "Content-Type: application/json" -u user:password -d '{"host_ip": "172.20.0.2", "node_name": "manager", "credentials": "<REDACTED>"}' "http://<manager-ip>/api/v3/cluster"

Response Example

{
    "initialized": false
}

PUT "{manager-ip}/api/v3/cluster"

Starts the cluster mechanisms on the current Cloudify Manager. If the join_addrs parameter is provided, joins an existing cluster, otherwise bootstraps a new cluster. When joining a cluster, the “credentials” parameter is required. To generate credentials for use by a new node, use the “Add cluster node” endpoint first. Only admin users can execute this operation.

Request Body

Property	Type	Description
host_ip	string	The externally accessible IP of this node.
node_name	string	A unique name for this node to be used internally within the cluster.
credentials	string	When joining a node, provide the credentials received from the cluster active node.
join_addrs	list	IPs of the nodes to connect with. If not provided, a new cluster will be created.

Response

A ClusterState resource.

Patch Cluster State

Request Example

client.cluster.update(
    config_key='config_value'
)

$ curl -X PATCH -H "Content-Type: application/json" -d '{"config_key": "config_value"}' -u user:password "http://<manager-ip>/api/v3/cluster"

Response Example

{
    "initialized": true,
    "error": null
}

PATCH "{manager-ip}/api/v3/cluster"

Updates the cluster configuration. The request body is a mapping containing arbitrary settings, which can be used by either the core cluster mechanisms, or user-specific extensions, if any. Only admin users can execute this operation.

Response

A ClusterState resource.

The ClusterNode resource

The ClusterNode resource represents the state of a node in the cluster

Attributes:

Attribute	Type	Description
`master`	boolean	Whether this node is the current cluster master.
`name`	string	The name of this node.
`host_ip`	string	The externally accessible IP of this node.
`online`	boolean	Whether this node is currently online.
`initialized`	boolean	Whether the node has been successfully joined to the cluster.
`credentials`	dict	Credentials used by this node to join the cluster.

List Cluster Nodes

Request Example

client.cluster.nodes.list()

$ curl --header -u user:password "http://<manager-ip>/api/v3/cluster/nodes"

Response Example

{
    "items":
    [
        {
            "initialized": true,
            "online": true,
            "master": true,
            "host_ip": "172.20.0.2",
            "name": "cloudify_manager_LMJZA2",
            "credentials": "<REDACTED>"
        }
    ]
}

GET "{manager-ip}/api/v3/cluster/nodes"

Lists all nodes in the cluster.

Response

Field	Type	Description
`items`	list	A list of `ClusterNode` resources

Get Cluster Node

Request Example

client.cluster.nodes.get("<node-id>")

$ curl --header -u user:password "http://<manager-ip>/api/v3/cluster/nodes/<node-id>"

Response Example

{
    "initialized": true,
    "online": true,
    "master": true,
    "host_ip": "172.20.0.2",
    "name": "cloudify_manager_LMJZA2",
    "credentials": "<REDACTED>"
}

GET "{manager-ip}/api/v3/cluster/nodes/{node-id}"

Fetches the details of a node in the cluster.

URI Parameters

node-id: The ID of the node to remove from the cluster

Response

A ClusterNode resource.

Add Cluster Node

Request Example

client.cluster.nodes.add(host_ip='172.20.0.3', node_name='second-manager')

$ curl -u user:password -d '{"host_ip": "172.20.0.3", "node_name": "second-manager"}' "http://<manager-ip>/api/v3/cluster/nodes"

var headers = {
   'content-type': 'application/json',
   'authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
}

var settings = {
  "url": "http://<manager-ip>/api/v3/cluster/nodes",
  "method": "GET",
  "headers": headers,
  "contentType": "application/json"
  "data": JSON.stringify({
      "host_ip": "172.20.0.3",
      "node_name": "second-manager"
  })
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Response Example

{
    "initialized": false,
    "online": false,
    "master": false,
    "host_ip": "172.20.0.3",
    "name": "second-manager",
    "credentials": "<REDACTED>"
}

PUT "{manager-ip}/api/v3/cluster/nodes/{node-name}"

Adds a node to the cluster. This prepares the cluster for contacting the new node, runs validations and generates credentials for use by a new node. The received credentials are passed in the “Join cluster” (“Put Cluster State”) API call.

Delete Cluster Node

Request Example

client.cluster.nodes.delete("<node-id>")

$ curl -X DELETE -u user:password "http://<manager-ip>/api/v3/cluster/nodes/<node-id>"

Response Example

{
    "initialized": true,
    "online": true,
    "master": true,
    "host_ip": "172.20.0.2",
    "name": "cloudify_manager_LMJZA2"
}

DELETE "{manager-ip}/api/v3/cluster/nodes/{node-id}"

Removes a node from the cluster. The node disconnects from the cluster and disables all cluster mechanisms. You cannot rejoin it to the cluster. Only admin users can execute this operation.

URI Parameters

node-id: The ID of the node to remove from the cluster

Response

A ClusterNode resource representing the node that was removed from the cluster.

Deployments

The Deployment Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	The id of the blueprint the deployment is based on.
`created_at`	datetime	The time when the deployment was created.
`created_by`	string	The name of the user that created the deployment.
`description`	string	Deployment description.
`groups`	object	A dictionary containing the groups definition of deployment.
`id`	string	A unique identifier for the deployment.
`inputs`	object	A dictionary containing key value pairs which represents a deployment input and its provided value.
`outputs`	object	A dictionary containing an outputs definition of a deployment.
`policy_triggers`	object	A dictionary containing policy triggers of a deployment.
`policy_types`	object	A dictionary containing policies of a deployment.
`tenant_name`	string	The name of the tenant that owns the deployment.
`updated_at`	datetime	The time the deployment was last updated at.
`workflows`	list	A list of workflows that can be executed on a deployment.

List Deployments

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "<manager-ip>/api/v3/deployments?_include=id"

# Using CloudifyClient
deployments = client.deployments.list(_include=['id'])
for deployment in deployments:
  print deployment

# Using requests
url = 'http://<manager-ip>/api/v3/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello1"
    },
    {
      "id": "hello2"
    },
    {
      "id": "hello3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/deployments"

Lists all deployments.

Response

Field	Type	Description
`items`	list	A list of `Deployment` resources.

Get Deployment

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/deployments?id=<deployment-id>&_include=id"

# Using CloudifyClient
client.deployments.get(deployment_id='<deployment-id>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3/deployments'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'id': '<deployment-id>',
    '_include': 'id',
}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "hello1"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 1,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/deployments?id={deployment-id}"

Gets a deployment.

URI Parameters

deployment-id: The id of the deployment.

Response

A Deployment resource.

Create Deployment

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"blueprint_id": "<blueprint-id>", "inputs": {...}}' \
    "http://<manager-ip>/api/v3/deployments/<deployment-id>?_include=id"

# Using CloudifyClient
client.deployments.create(
    blueprint_id='<blueprint-id>',
    deployment_id='<deployment-id>',
    inputs={...},
)

# Using requests
url = 'http://<manager-ip>/api/v3/deployments/<deployment-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={
    'blueprint_id': '<blueprint-id>',
    'inputs': {...},
}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "id": "hello4"
}

PUT -d '{"blueprint_id": "<blueprint-id>", "inputs": {...}}' "{manager-ip}/api/v3/deployments/{deployment-id}"

Creates a new deployment.

URI Parameters

deployment-id: The id of the new deployment.

Request Body

Property	Type	Description
`blueprint_id`	string	The id of the blueprint the new deployment will be based on (required).
`inputs`	object	The dictionary containing key value pairs which represents the deployment inputs.

Response

A Deployment resource.

Delete Deployment

Request Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/deployments/<deployment-id>?_include=id"

# Using CloudifyClient
client.deployments.delete(deployment_id='<deployments-id>')

# Using requests
url = 'http://<manager-ip>/api/v3/deployments/<deployment-id>'
headers = {'content-type': 'application/json'}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "hello4"
}

DELETE "{manager-ip}/api/v3/deployments/{deployment-id}"

Deletes a deployment.

An error is raised if the deployment has any live node instances. In order to ignore this validation, the ignore_live_nodes argument in request body can be used.

URI Parameters

deployment-id: The id of the deployment.

Request Body

Property	Type	Description
`ignore_live_nodes`	boolean	Specifies whether to ignore the live nodes validation.

Response

A Deployment resource.

Events

The Event Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	Blueprint id
`deployment_id`	string	Deployment id
`error_causes`	[ErrorCause]	List of errors that happened while executing a given task (only for `cloudify_event` items)
`event_type`	string	Event type name (only for `cloudify_event` items)
`execution_id`	string	Execution id
`level`	string	Log level (only for `cloudify_log` items)
`logger`	string	Logger id (only for `cloudify_log` items)
`message`	string	Message text
`node_instance_id`	string	Node instance id
`node_name`	string	Node name
`operation`	string	Operation path (only available in operation events)
`reported_timestamp`	ISO 8601	The time at which the event occurred on the executing machine
`timestamp`	ISO 8601	The time at which the event was logged on the management machine
`type`	string	Indicates whether the resource is a `cloudify_event` or a `cloudify_log`
`workflow_id`	string	Workflow id

The ErrorCause object

Attribute	Type	Description
`message`	string	Error message
`traceback`	string	Stack trace at the point where the exception was raised
`type`	string	Exception type

List events

Lists all events

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u user:<manager-password> \
    "http://<manager_ip>/api/v3/events"

# Using Cloudify client
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
    host='<manager-ip>',
    username='<manager-username>',
    password='<manager-password>',
    tenant='<manager-tenant>')
events = client.events.list()
for event in events:
    print event

# Using requests
import requests
from requests.auth import HTTPBasicAuth

url = 'http://<manager-ip>/api/v3/events'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(url, auth=HTTPBasicAuth('user', '<manager-password>'), headers=headers)
response.json()

Response Example

{
  "items": [
    {
      "node_instance_id": "vm_ke9e2d",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:41:59.169Z",
      "message": "Successfully configured cfy-agent",
      "level": "info",
      "node_name": "vm",
      "workflow_id": "install",
      "reported_timestamp": "2017-03-22T11:41:59.169Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_log",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387",
      "logger": "22e710c6-18b8-4e96-b8a3-2104b81c5bfc"
    },
    {
      "node_instance_id": "vm_ke9e2d",
      "event_type": "task_succeeded",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:42:00.083Z",
      "message": "Task succeeded 'cloudify_agent.installer.operations.create'",
      "node_name": "vm",
      "workflow_id": "install",
      "error_causes": null,
      "reported_timestamp": "2017-03-22T11:42:00.083Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_event",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387"
    },
    {
      "node_instance_id": "vm_ke9e2d",
      "event_type": "task_failed",
      "operation": "cloudify.interfaces.cloudify_agent.create",
      "blueprint_id": "linuxbp1",
      "timestamp": "2017-03-22T11:43:01.823Z",
      "message": "Task failed 'cloudify_agent.installer.operations.create' -> ERROR_MESSAGE",
      "node_name": "vm",
      "workflow_id": "install",
      "error_causes": [
        {
          "message": "ERROR_MESSAGE",
          "traceback": "Traceback (most recent call last):\n  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/cloudify/dispatch.py\", line 624, in main\n
  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/cloudify/dispatch.py\", line 389, in handle\n  File \"/opt/mgmtworker/env/lib/python2.7/site-packages/t
estmockoperations/tasks.py\", line 476, in execution_logging\n    raise NonRecoverableError('ERROR_MESSAGE', causes=causes)\nNonRecoverableError: ERROR_MESSAGE\n",
          "type": "NonRecoverableError"
        }
      ],
      "reported_timestamp": "2017-03-22T11:43:01.823Z",
      "deployment_id": "linuxdp1",
      "type": "cloudify_event",
      "execution_id": "19ce78d6-babc-4a18-ba8e-74b853f2b387"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 10000
    }
  }
}

GET "{manager-ip}/api/v3/events"

List events within a time range

GET "{manager-ip}/api/v3/events?_range=timestamp,[time_start],[time_end]"

Parameter	Type	Description
`time_start`	ISO 8601	optional value to begin range with.
`time_end`	ISO 8601	optional value to end range with.

all events within a time range:

GET "/api/v3/events?_range=timestamp,<time_start>,<time_end>"

all events since a given time:

GET "/api/v3/events?_range=timestamp,<time_start>,

all events until a given time:

GET "/api/v3/events?_range=timestamp,,<time_end>"

List events with filters

GET "{manager-ip}/api/v3/events?<filter>"

Allowed filters:

blueprint_id
deployment_id
execution_id
event_type (only returns cloudify-event items)
level (only returns cloudify-log items)
message(SQL’s LIKE style pattern expected)

Multiple filters can be passed in the same request:

Filters of the same type will be combined using a logical OR operator
Filters of differnt type will be combined using a logical AND operator.

Response

Field	Type	Description
`items`	list	A list of `Event` resources.
`metadata`	object	Pagination metadata

Executions

The Execution Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	The id of the blueprint the execution is in the context of.
`created_at`	datetime	The time the execution was queued at.
`created_by`	string	The name of the user that created the execution.
`deployment_id`	string	The id of the deployment the execution is in the context of.
`error`	string	The execution’s error message on execution failure.
`id`	string	A unique identifier for the execution.
`is_system_workflow`	boolean	true if the execution is of a system workflow.
`parameters`	object	A dict of the workflow parameters passed when starting the execution.
`status`	string	The executions status.
`tenant_name`	string	The name of the tenant that owns the execution.
`workflow_id`	string	The id/name of the workflow the execution is of.

List Executions

Request Example

$ curl -X GET "<manager-ip>/api/v3/executions?_include=id

# Using CloudifyClient
executions = client.executions.list(_include=['id'])
for execution in executions:
  print execution

# Using requests
url = 'http://<manager-ip>/api/v3/executions'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)

Response Example

{
  "items": [
    {
      "id": "dab3d7ac-fef0-4b8b-912f-5611cc8f20b5"
    },
    {
      "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/executions"

Lists all executions.

Response

Field	Type	Description
`items`	list	A list of `Execution` resources.

Get Execution

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/executions/<execution-id>?_include=id"

# Using CloudifyClient
client.executions.get(execution_id='<execution_id>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3/executions/<execution_id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "ca3d7413-c8af-41a3-b864-571cef25899b"
}

GET "{manager-ip}/api/v3/executions/{execution-id}"

Gets an execution.

URI Parameters

execution-id: The id of the execution.

Response

An Execution resource.

Start Execution

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_id": "<deployment-id>", "workflow_id": "install"}' \
    "http://<manager_ip>/api/v3/executions?_include=id"

# Using CloudifyClient
client.executions.start(deployment_id='<deployment-id>', workflow_id='install')

# Using requests
url = 'http://<manager-ip>/api/v3/executions'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={
    'deployment_id': '<deployment-id>',
    'workflow_id': 'install',
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response example

{
  "id": "33dd51d4-5e24-4034-8ed6-2150cdbd98f7"
}

POST -d '{"deployment_id":{deployment-id}, "workflow_id":"<workflow-id>"}' "{manager-ip}/api/v3/executions"

Starts an execution.

Request Body

Property	Type	Description
`workflow_id`	string	The workflow id/name to execute.
`deployment_id`	string	The id of the deployment the workflow should be executed on.
`allow_custom_parameters`	boolean	Specifies whether to allow custom parameters, which are not present in the parameters schema of the workflow, to be passed when starting the execution (default=false).
`parameters`	object	A dictionary containing parameters to be passed to the execution when starting it.
`force`	boolean	Specifies whether to force the workflow execution in a case where there is already a running execution in the context of the same deployment or system wide workflow (default=false).

Response

An Execution resource.

Cancel Execution

Request Example

curl -X POST \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"deployment_id": "dep", "action": "cancel"}'
    "http://<manager-ip>/api/v3/executions/<execution-id>?_include=id"

# Using CloudifyClient
client.executions.cancel(execution_id='<execution-id>')

# Using requests
url = 'http://<manager-ip>/api/v3/executions/<execution-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={'deployment_id': 'dep', 'action': 'cancel'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Example Response

{
  "id": "e7821510-c536-47f3-8fe7-691a91dc91ff"
}

POST -d '{"deployment_id":{deployment-id}, "action":"<action-method>"}' "{manager-ip}/api/v3/executions/{execution-id}"

Cancels an execution.

If passing cancel as the action fails to cancel the execution, force-cancel can be passed which will then kill the process running the execution.

URI Parameters

execution-id: The id of the execution.

Request Body

Property	Type	Description
`action`	string	The cancellation method to perform: `cancel` or `force-cancel`

Response

An Execution resource.

Update Execution

Request Example

curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"status": "cancelled"}' \
    "http://<manager-ip>/api/v3/executions/<execution-id>?_include=id"

# Using CloudifyClient
client.executions.update(execution_id='<execution_id>', status='cancelled')

# Using requests
url = 'http://<manager-ip>/api/v3/executions/<execution-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload ={'status': 'cancelled'}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Example Response

{
  "id": "21236984-9d1f-445e-8bca-f923175441f1"
}

PATCH "{manager-ip}/api/v3/executions/{execution-id}"

Updates an execution.

URI Parameters

execution-id: The id of the execution.

Request Body

Property	Type	Description
`status`	string	The new status of the execution.

Response

An Execution resource.

Manager

The following REST API calls provide information about Cloudify’s manager.

Status

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/status"

# Using ClodifyManager
client.manager.get_status()

# Using requests
url = 'http://<manager-ip>/api/v3/status'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'status'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "status": "running"
}

GET "{manager-ip}/api/v3/status"

Gets Cloudify manager status.

Attributes:

Attribute	Type	Description
`status`	string	The status of the manager. Will always have a “running” value.
`services`	list	List of Service resources each, representing a service running in the manager.

The Service Object:

Attribute	Type	Description
`instances`	list	List of Instance resources representing the instances of a service running in a manager in a DBus structure.
`display_name`	string	The service name.

The Instance Object:

Attribute	Type	Description
`LoadState`	string	Contains a state value that reflects whether the configuration file of this unit has been loaded.
`Description`	string	The description of the service instance.
`state`	string	The state of the service instance (unknown, down, up, finish).
`MainPID`	integer	The process id of the main service instance process.
`Id`	string	The id of the service instance.
`ActiveState`	string	Contains a state value that reflects whether the unit is currently active or not. The following states are currently defined: active, reloading, inactive, failed, activating, deactivating.
`SubState`	string	Encodes states of the same state machine that `ActiveState` covers, but knows more fine-grained states that are unit-type-specific.

Information about the instance fields can be found in the DBus reference.

Version

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/version?_include=version"

# Using CloudifyClient
client.manager.get_version()

# Using requests
url = 'http://<manager-ip>/api/v3/version'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'version'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "version": "4.0.1"
}

GET "{manager-ip}/api/v3/version"

Gets Cloudify manager version information.

Attributes:

Attribute	Type	Description
`date`	ISO 8601	The date and time of the build the manager was built of.
`commit`	string	Git commit hash of the REST service code base used by the manager.
`version`	string	The version of Cloudify manager.
`build`	string	Build number.
`edition`	string	Software edition (either `community` or `premium`)

Node Instances

The NodeInstance Resource

Attributes:

Attribute	Type	Description
`created_by`	string	The name of the user that created the node instance.
`deployment_id`	string	The id of the deployment the node instance belongs to.
`host_id`	string	The Compute node instance id the node is contained within.
`id`	string	The id of the node instance.
`relationships`	list	The relationships the node has with other nodes.
`runtime_properties`	object	The runtime properties of the node instance.
`state`	string	The node instance state.
`tenant_name`	string	The name of the tenant that owns the node instance.
`version`	integer	A version attribute used for optimistic locking when updating the node instance.

List Node Instances

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/node-instances&_include=id"

# Using CloudifyClient
instances = client.node_instances.list(_include=['id'])
for instance in instances:
    print instance

# Using requests
url = 'http://<manager-ip>/api/v3/node-instances'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "http_web_server_tfq3nt"
    },
    {
      "id": "vm_m7nmd7"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/node-instances"

Lists all node instances.

Response

Field	Type	Description
`items`	list	A list of `NodeInstance` resources.

Get Node Instance

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/node-instances/<node-instance-id>&_include=id"

# Using CloudifyClient
client.node_instances.get('http_web_server_tfq3nt', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3/node-instances/<node-instance-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "http_web_server_tfq3nt"
}

GET "{manager-ip}/api/v3/node-instances/{node-instance-id}"

Gets a node instance.

URI Parameters

node-instance-id: The id of the node instance.

Response

A NodeInstance resource.

Update Node Instance

Requests Example

$ curl -X PATCH \
    --header "Tenant: <manager-tenant>" \
    --header "Content-Type: application/json" \
    -u <manager-username>:<manager-password> \
    -d '{"version": 0, "runtime_properties": {"key": "value"}}' \
    "http://<manager-ip>/api/v3/node-instances/<node-instance-id>?_include=id,runtime_properties"

# Using CloudifyClient
client.node_instances.update(
    node_instance_id='<node-instance-id>',
    version=0,
    runtime_properties={'key': 'value'},
)

# Using requests
url = 'http://<manager-ip>/api/v3/node-instances/<node-instance-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager_tenant>',
}
querystring = {'_include': 'id,runtime_properties'}
payload = {'version': 0, 'runtime_properties': {'key': 'value'}}
response = requests.patch(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

Response Example

{
  "runtime_properties": {
    "key": "value"
  },
  "id": "http_web_server_tfq3nt"
}

PATCH "{manager-ip}/api/v3/node-instances/{node-instance-id}"

Updates a node instance.

URI Parameters

node-instance-id: The id of the node instance.

Request Body

Property	Type	Description
`runtime_properties`	object	A dictionary containing the updated runtime properties of the node instance.
`state`	string	The new state of the node instance.
`version`	integer	The node instance current version (used for optimistic locking).

The version property should be set to the current value of the node instance. The version is auto incremented by Cloudify on every update.

Response

A NodeInstance resource.

Nodes

The Node Resource

Attributes:

Attribute	Type	Description
`blueprint_id`	string	The id of the blueprint the node belongs to.
`deploy_number_of_instances`	integer	Default number of instances on deploy.
`deployment_id`	string	The id of the deployment the node belongs to.
`host_id`	string	The Compute node name the node is contained within.
`id`	string	The name of the node.
`max_number_of_instances`	integer	Maximum number of instances.
`min_number_of_instances`	integer	Minimum number of instances.
`number_of_instances`	integer	The number of node instances the node has.
`operations`	object	The operations the node exposes.
`planned_number_of_instances`	integer	-
`plugins_to_install`	list	A list of required plugins to install in order to execute the node’s operations.
`plugins`	list	A list of plugins the node is using for executing its operations.
`properties`	object	The properties of the node.
`relationships`	list	The relationships the node has with other nodes.
`tenant_name`	string	The name of the tenant that owns the node.
`type_hierarchy`	list	The type hierarchy of the node (ancestors).
`type`	string	The type of the node.

id and deployment_id are combined together for uniquely identifying a node.

List Nodes

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/nodes?_include=id"

# Using CloudifyClient
nodes = client.nodes.list(_include=['id'])
for node in nodes:
    print node

# Using request
url = 'http://<manager-ip>/api/v3/nodes'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "http_web_server"
    },
    {
      "id": "vm"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/nodes"

Lists all nodes.

Response

Field	Type	Description
`items`	list	A list of `Node` resources.

Plugins

The Plugin Resource

Attributes:

Attribute	Type	Description
`archive_name`	string	The plugin archive file name.
`distribution_release`	string	The OS distribution release name the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
`distribution_version`	string	The OS distribution version the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
`distribution`	string	The OS distribution the plugin was compiled on. ‘None’ in-case the plugin is cross platform.
`excluded_wheels`	list	a list of wheels that were excluded from the plugin package.
`id`	string	The ID assigned to the plugin upon upload.
`package_name`	string	The python package name.
`package_source`	string	The python package source, i.e git, pip etc.
`package_version`	string	The python package version.
`supported_platform`	string	The supported platform for the plugin package, ‘any’ if the plugin is compatible with all platforms.
`supported_py_versions`	list	a list of python platforms supported by the plugin.
`tenant_name`	string	The name of the tenant that owns the plugin.
`uploaded_at`	ISO 8601	The time and date the plugin was uploaded on to the Cloudify-Manager.
`wheels`	list	A list of wheels contained in the plugin package.

List Plugins

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/plugins?_include=id"

# Using CloudifyClient
plugins = client.plugins.list(_include=['id'])
for plugin in plugins:
    print plugin

# Using requests
url = 'http://<manager-ip>/api/v3/plugins'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "ecea687a-b7dc-4d02-909d-0400aa23df27"
    },
    {
      "id": "f10a4970-6cfa-4b24-9cab-f85db93204e0"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 2,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/plugins"

Lists all plugins.

Response

Field	Type	Description
`items`	list	A list of `Plugin` resources.
`metadata`	dict	Metadata relevant to the list response.

Get Plugin

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/plugins/<plugin-id>?_include=id"

# Using CloudifyClient
client.plugins.get(plugin_id='<plugin-id'>', _include=['id'])

# Using requests
url = 'http://<manager-ip>/api/v3/plugins/<plugin-id>'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "id": "ecea687a-b7dc-4d02-909d-0400aa23df27"
}

GET "{manager-ip}/api/v3/plugins/{plugin-id}"

Gets a plugin.

URI Parameters

plugin-id: The id of the plugin.

Response

A Plugin resource.

Delete Plugin

Request Example

$ curl -X DELETE \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"force": false}' \
    "http://<manager-ip>/api/v3/plugins/<plugin-id>?_include=id"

# Using CloudifyClient
client.plugins.delete(plugin_id='<plugin-id>')

# Using requests
url = 'http://<manager-ip>/api/v3/plugins/<plugin-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
querystring = {'_include': 'id'}
payload = {'force': False}
response = requests.delete(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
    json=payload,
)
response.json()

DELETE "{manager-ip}/api/v3/plugins/{plugin-id}"

Deletes a plugin from the Cloudify-Manager.

URI Parameters

plugin-id: The id of the plugin.

Request Body

Property	Default	Description
`force`	false	Specifies whether to force plugin deletion even if there are deployments that currently use it.

Response

The deleted Plugin resource.

Upload Plugin

Request Example

$ curl -X POST \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/plugins?plugin_archive_url=http://url/to/archive.wgn&_include=id"

# Using CloudifyClient
client.plugins.upload(plugin_path='http://url/to/archive.wgn')

# Using requests
url = 'http://<manager-ip>/api/v3/plugins'
headers = {'Tenant': '<manager-tenant>'}
querystring = {
    'plugin_archive_url': 'http://url/to/archive.wgn',
    '_include': 'id',
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Example Response

{
  "id": "d80542f4-ec0c-4438-8a29-54cb9a904114"
}

POST "{manager-ip}/api/v3/plugins"

Upload a plugins

Request Body

Property	Type	Description
`plugin_path`	string	The plugin archive local path.
`plugin_archive_url`	string	A URL of the plugin archive to be uploaded. The plugin will be downloaded by the manager.

Response

The new uploaded Plugin resource.

Download Plugin

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/plugins/<plugin-id>/archive" > <plugin-archive-filename>.wgn

# Using CloudifyClient
client.plugins.download(
   plugin_id='<plugin-id>',
   output_file='<plugin-archive-filename>',
)

# Using Requests
url = 'http://<manager-ip>/api/v3/plugins/<plugin-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<plugin-archive-filename>.wgn', 'wb') as plugin_archive:
    plugin_archive.write(response.content)

GET "{manager-ip}/api/v3/plugins/{plugin-id}/archive"

Downloads a plugin.

URI Parameters

plugin-id: The id of the plugin.

Response

The requested plugin archive.

Secrets

The Secret Resource

Note

# include this code when using cloudify python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>',
        tenant='<manager-tenant>')

A Secret resource is a key-value pair saved per tenant. A user can ensure all secrets (such as credentials to IaaS environments, passwords, etc) are kept in a secured manner, and adhere to isolation requirements between different tenants.

Attributes:

Attribute	Type	Description
`created_at`	datetime	The time when the secret was created.
`key`	string	The secret’s key, unique per tenant.
`updated_at`	datetime	The time the secret was last updated at.
`value`	string	The secret’s value.

List Secrets

Request Example

$ curl -X GET --header "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/secrets"

# Python Client-
client.secrets.list()

Response Example

{
 "items":
    [
        {
            "key": "key1",
            "created_at": "2017-03-20T08:23:31.276Z",
            "updated_at": "2017-03-20T08:43:19.468Z",
            "permission": "creator",
            "tenant_name": "default_tenant",
            "created_by": "admin"
        }
    ]
}

GET "{manager-ip}/api/v3/secrets"

List all secrets.

Response

Field	Type	Description
`items`	list	A list of `Secret` resources without the secret’s value.

Get Secret

Request Example

$ curl -X GET --header "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/secrets/<secret-key>"

# Python Client-
client.secrets.get(<secret-key>)

Response Example

{
    "key": "key1",
    "value": "value1",
    "created_at": "2017-03-20T08:23:31.276Z",
    "updated_at": "2017-03-20T08:43:19.468Z",
    "permission": "creator",
    "tenant_name": "default_tenant",
    "created_by": "admin"
}

GET "{manager-ip}/api/v3/secrets/{secret-key}"

Retrieves a specific secret.

URI Parameters

secret-key: The key of the secret to retrieve.

Response

A Secret resource.

Create Secret

Request Example

$ curl -X PUT -H "Content-Type: application/json" -H "tenant: <tenant-name>" -d '{"value": <new-secret-value>}' -u user:password "http://<manager-ip>/api/v3/secrets/<new-secret-key>"

# Python Client-
client.secrets.create(<new-secret-key>, <new-secret-value>)

Response Example

{
    "key": "key1",
    "value": "value1",
    "created_at": "2017-03-20T08:23:31.276Z",
    "updated_at": "2017-03-20T08:23:31.276Z",
    "permission": "creator",
    "tenant_name": "default_tenant",
    "created_by": "admin"
}

PUT -d '{"value": <new-secret-value>}' "{manager-ip}/api/v3/secrets/{new-secret-key}"

Creates a secret.

URI Parameters

new-secret-key: The key of the secret to create.

Request Body

Property	Type	Description
`value`	string	The secret’s value.

Response

A Secret resource.

Update Secret

Request Example

$ curl -X PATCH -H "Content-Type: application/json" -H "tenant: <tenant-name>" -d '{"value": <new-value>}' -u user:password "http://<manager-ip>/api/v3/secrets/<secret-key>"

# Python Client-
client.secrets.update(<secret-key>, <new-value>)

Response Example

{
    "key": "key1",
    "value": "value1",
    "created_at": "2017-03-20T08:23:31.276Z",
    "updated_at": "2017-03-20T08:43:19.468Z",
    "permission": "creator",
    "tenant_name": "default_tenant",
    "created_by": "admin"
}

PATCH -d '{"value": <new-value>}' "{manager-ip}/api/v3/secrets/{secret-key}"

Updates a secret.

URI Parameters

secret-key: The key of the secret to update.

Request Body

Property	Type	Description
`value`	string	The secret’s new value.

Response

A Secret resource.

Delete Secret

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/secrets/<secret-key>"

# Python Client-
client.secrets.delete(<secret-key>)

Response Example

{
    "key": "key1",
    "value": "value1",
    "created_at": "2017-03-20T08:23:31.276Z",
    "updated_at": "2017-03-20T08:43:19.468Z",
    "permission": "creator",
    "tenant_name": "default_tenant",
    "created_by": "admin"
}

DELETE "{manager-ip}/api/v3/secrets/{secret-key}"

Deletes a secret.

URI Parameters

secret-key: The key of the secret to delete.

Response

A Secret resource.

Snapshots

The Snapshot Resource

Attributes:

Attribute	Type	Description
`created_at`	ISO 8601	The time the snapshot was uploaded to or created on the manager.
`error`	string	Message of an error if snapshot creation failed.
`id`	string	A unique identifier of the snapshot.
`status`	string	Status of the snapshot. One of created/failed/uploading/uploaded.

List Snapshots

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/snapshots?_include=id"

# Using CloudifyClient
snapshots = client.snapshots.list(_include=['id'])
for snapshot in snapshots:
    print snapshot

# Using requests
url = 'http://<manager-ip>/api/v3/snapshots'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'_include': 'id'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "items": [
    {
      "id": "snapshot1"
    },
    {
      "id": "snapshot2"
    },
    {
      "id": "snapshot3"
    }
  ],
  "metadata": {
    "pagination": {
      "total": 3,
      "offset": 0,
      "size": 0
    }
  }
}

GET "{manager-ip}/api/v3/snapshots"

Lists all snapshots.

Response

Attribute	Type	Description
`items`	list	A list of Snapshot resources.

Create Snapshot

Requests Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/snapshots/<snapshot-id>"

# Using CloudifyClient
client.snapshots.create(
    snapshot_id='<snapshot-id>',
    include_metrics=False,
    include_credentials=False,
)


# Using requests
url = 'http://<manager-ip>/api/v3/snapshots/<snapshot-id>'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {}
response = requests.put(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Response Example

{
  "status": "pending",
  "parameters": {
    "include_metrics": false,
    "config": {
      "postgresql_db_name": "cloudify_db",
      "default_tenant_name": "default_tenant",
      "postgresql_bin_path": "/usr/pgsql-9.5/bin/",
      "failed_status": "failed",
      "postgresql_username": "cloudify",
      "db_port": 9200,
      "postgresql_password": "cloudify",
      "created_status": "created",
      "db_address": "localhost",
      "file_server_root": "/opt/manager/resources",
      "postgresql_host": "localhost"
    },
    "include_credentials": true,
    "snapshot_id": "snapshot4"
  },
  "is_system_workflow": true,
  "blueprint_id": null,
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T16:16:45.948Z",
  "created_by": "admin",
  "private_resource": false,
  "workflow_id": "create_snapshot",
  "error": "",
  "deployment_id": null,
  "id": "bb9cd6df-7acd-4649-9fc1-fe062759cde8"
}

PUT "{manager-ip}/api/v3/snapshots/{snapshot-id}"

Creates a new snapshot.

URI Parameters

snapshot-id: The id of the new snapshot.

Request Body

Property	Type	Description
`include_metrics`	string	Specifies whether metrics stored in InfluxDB should be included in the created snapshot. It defaults to false.
`include_credentials`	string	Specifies whether agent SSH keys (including those specified in uploaded blueprints) should be included in the created snapshot. It defaults to false.

Response

An Execution resource representing the create snapshot workflow execution.

Delete Snapshot

Requests Example

$ curl -X DELETE \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/snapshots/<snapshot-id>"

# Using CloudifyClient
client.snapshots.delete(snapshot_id='<snapshot-id>')

# Using requests
url = 'http://<manager-ip>/api/v3/snapshots/<snapshot-id>'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Example Response

{
  "status": "uploaded",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T17:04:22.989Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "snapshot4"
}

DELETE "{manager-ip}/api/v3/snapshots/{snapshot-id}"

Deletes an existing snapshot.

URI Parameters

snapshot-id: The id of the snapshot to be deleted.

Response

An empty Snapshot resource, with one non-empty field (its id).

Restore Snapshot

Requests Example

curl -s -X POST \
    --header "Content-Type: application/json" \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    -d '{"recreate_deployments_envs": true, "force": false, "restore_certificates": false, "no_reboot": false}' \
    "http://<manager-ip>/api/v3/snapshots/<snapshot-id>/restore"

# Using CloudifyClient
client.snapshots.restore(snapshot_id='<snapshot-id>', tenant_name='<manager-tenant>')

# Using requests
url = 'http://<manager-ip>/api/v3/snapshots/<snapshot-id>/restore'
headers = {
    'Content-Type': 'application/json',
    'Tenant': '<manager-tenant>',
}
payload = {
    'recreate_deployments_envs': True,
    'force': False,
    'restore_certificates': False,
    'no_reboot': False
}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    json=payload,
)
response.json()

Example Response

{
  "status": "pending",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T17:23:30.779Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "1cadbb76-4532-4eae-a139-80bff328944d"
}

POST "{manager-ip}/api/v3/snapshots/{snapshot-id}/restore"

Restores the specified snapshot on the manager.

URI Parameters

snapshot-id: The id of the snapshot to be restored.

Request Body

Property	Default	Description
`force`	false	Specifies whether to force restoring the snapshot on a manager that already contains blueprints/deployments.
`recreate_deployments_envs`	true	Specifies whether deployment environments should be created for restored deployments.
`restore_certificates`	false	Specifies whether to try and restore the certificates from the snapshot and use them to override the current Manager certificates, in the event that snapshot’s certificates metadata does not match the current Manager’s certificates metadata. Useful when there are live agents from the Manager from which the snapshot was created that you want to control with the current Manager. After execution the Manager will automatically reboot - unless the `no_reboot` property is `True`.
`no_reboot`	false	Only relevant when the `restore_certificates` property is `True`. Specifies whether to the automatic reboot at the end of the snapshot restore execution. It is not recommended to use this option since the Manager will not function well after certificates restore without a reboot. In that case, you must manually reboot the machine.

Response

An Execution resource representing the restore snapshot workflow execution.

Download Snapshot

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/snapshot/<snapshot-id>/archive" > <snapshot-archive-filename>.zip

# Using CloudifyClient
client.snapshots.download(
    snapshot_id='<snapshot-id>',
    output_file='<snapshot-archive-filename>.zip',
)

# Using requests
url = 'http://<manager-ip>/api/v3/snapshot/<snapshot-id>/archive'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
with open('<snapshot-archive-filename>.wgn', 'wb') as snapshot_archive:
    snapshot_archive.write(response.content)

GET "{manager-ip}/api/v3/snapshots/{snapshot-id}/archive"

Downloads an existing snapshot.

URI Parameters

snapshot-id: The id of the snapshot to be downloaded.

Response

A streamed response (content type application/octet-stream), which is a zip archive containing the snapshot data.

Upload Snapshot

Request Example

$ curl -X PUT \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/snapshots/archive?snapshot_archive_url=http://url/to/archive.zip"

# Using CloudifyClient
client.snapshots.upload(
    snapshot_id='<snapshot-id>',
    snapshot_path='http://url/to/archive.zip',
)

# Using requests
url = 'http://<manager-ip>/api/v3/snapshots/archive'
headers = {'Tenant': '<manager-tenant>'}
querystring = {'snapshot_archive_url': 'http://url/to/archive.zip'}
response = requests.post(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
    params=querystring,
)
response.json()

Response Example

{
  "status": "uploaded",
  "tenant_name": "default_tenant",
  "created_at": "2017-05-11T18:13:25.912Z",
  "created_by": "admin",
  "private_resource": false,
  "error": "",
  "id": "snapshot5"
}

PUT "{manager-ip}/api/v3/snapshots/{snapshot-id}/archive"

Uploads a snapshot to the Cloudify Manager. The call expects a application/octet-stream content type where the content is a zip archive. It is possible to upload a snapshot from a URL by specifying the URL in the snapshot_archive_url request body property.

URI Parameters

snapshot-id: The id of the snapshot to be uploaded.

Request Body

Property	Type	Description
`snapshot_archive_url`	string	Optional parameter specifying a url to a snapshot that will be uploaded to the manager.

Response

A Snapshot resource.

Tenants

The Tenant Resource

Note

# include this code when using cloudify python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>',
        tenant='<manager-tenant>')

The Tenant resource is a logical component that represents a closed environment with its own resources.

Attributes:

Attribute	Type	Description
`id`	integer	Auto increment, unique identifier for the tenant.
`name`	string	The tenant’s name.

List Tenants

Request Example

$ curl -X GET --header "tenant: default_tenant" -u user:password "http://<manager-ip>/api/v3/tenants"

# Python Client-
client.tenants.list()

Response Example

{
 "items":
    [
        {
            "name": "default_tenant",
            "groups": [],
            "users": ["admin"]
        }
    ]
}

GET "{manager-ip}/api/v3/tenants"

List all tenants.

Response

Field	Type	Description
`items`	list	A list of `Tenant` resources.

Get Tenant

Request Example

$ curl -X GET --header "tenant: default_tenant" -u user:password "http://<manager-ip>/api/v3/tenants/{tenant-name}"

# Python Client-
client.tenants.get('default_tenant')

Response Example

{
    "name": "default_tenant",
    "groups": [],
    "users": ["admin"]
}

GET "{manager-ip}/api/v3/tenants?name={tenant-name}"

Retrieves a specific tenant.

URI Parameters

tenant-name: The name of the tenant to retrieve.

Response

A Tenant resource.

Create Tenant

Request Example

$ curl -X POST -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/tenants/<new-tenant-name>"

# Python Client-
client.tenants.create(<new-tenant-name>)

Response Example

{
    "name": "new_tenant",
    "groups": [],
    "users": []
}

POST "{manager-ip}/api/v3/tenants/{new-tenant-name}"

Creates a tenant.

URI Parameters

new-tenant-name: The name of the tenant to create.

Response

A Tenant resource.

Delete Tenant

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/tenants/<tenant-name-to-delete>"

# Python Client-
client.tenants.delete(<tenant-name>)

Response Example

{
    "name": "tenant-name",
    "groups": [],
    "users": []
}

DELETE "{manager-ip}/api/v3/tenants/{tenant-name-to-delete}"

Delete a tenant.

URI Parameters

tenant-name-to-delete: The name of the tenant to delete.

Response

A Tenant resource.

Add User to Tenant

Request Example

$ curl -X PUT -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"username": <user-name>, "tenant_name": <tenant-name>}' `"http://<manager-ip>/api/v3/tenants/users"

# Python Client-
client.tenants.add_user(<user-name>, <tenant-name>)

Response Example

{
    "name": "tenant-name",
    "groups": [],
    "users": []
}

PUT "{manager-ip}/api/v3/tenants/users"

Add a user to a tenant.

Request Body

Property	Type	Description
`username`	string	The user name to add to the tenant.
`tenants_name`	string	The name of the tenant to which to add the user.

Response

A Tenant resource.

Remove User from Tenants

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"username": <user-name>, "tenants_name": <tenants-name>}' `"http://<manager-ip>/api/v3/tenants/users"

# Python Client-
client.tenants.remove_user(<user-name>, <tenant-name>)

Response Example

{
    "name": "tenant-name",
    "groups": [],
    "users": []
}

DELETE "{manager-ip}/api/v3/tenants/users"

Delete a user from a tenant.

Request Body

Property	Type	Description
`username`	string	The user name to remove from the tenant.
`tenant_name`	string	The tenant name to add the user into it.

Response

A Tenant resource.

Add User-Group to Tenant

Request Example

$ curl -X PUT -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"group_name": <group-name>, "tenant_name": <tenant-name>}' `"http://<manager-ip>/api/v3/tenants/user-groups"

# Python Client-
client.tenants.add_group(<group-name>, <tenant-name>)

Response Example

{
    "name": "tenant-name",
    "groups": ["new_group"],
    "users": []
}

PUT "{manager-ip}/api/v3/tenants/user-groups"

Add a user group to a tenant.

Request Body

Property	Type	Description
`group_name`	string	The name of the user group to add to the tenant.
`tenants_name`	string	The name of the tenant to which to add the user group.

Response

A Tenant resource.

Remove User-Group from Tenants

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"group_name": <group-name>, "tenants_name": <tenants-name>}' `"http://<manager-ip>/api/v3/tenants/user-groups"

# Python Client-
client.tenants.remove_user(<group-name>, <tenant-name>)

Response Example

{
    "name": "tenant-name",
    "groups": [],
    "users": []
}

DELETE "{manager-ip}/api/v3/tenants/user-groups"

Delete a user group from a tenant.

Request Body

Property	Type	Description
`group_name`	string	The name of the user group to delete from the tenant.
`tenant_name`	string	The name of the tenant from which to delete the user group.

Response

A Tenant resource.

Tokens

The Tokens Resource

Attributes:

Attribute	Type	Description
`role`	string	The role associated with the token (`admin` or `user`)
`value`	string	The value of the token

Get Token

Request Example

$ curl -X GET \
    --header "Tenant: <manager-tenant>" \
    -u <manager-username>:<manager-password> \
    "http://<manager-ip>/api/v3/tokens"

# Using CloudifyClient
client.tokens.get()

# Using requests
url = 'http://<manager-ip>/api/v3/tokens'
headers = {'Tenant': '<manager-tenant>'}
response = requests.get(
    url,
    auth=HTTPBasicAuth('<manager-username>', '<manager-password>'),
    headers=headers,
)
response.json()

Response Example

{
  "role": "admin",
  "value": "WyIwIiwiZjRmNTUzMWRmYmFmZGZmNTlkNTkyZGY2MjMxYzkyNTEiXQ.C_YU9Q.IhQMlnXZIaCtWUUHH_CzHP4-Bg4"
}

GET "{manager-ip}/api/v3/tokens"

Gets a token.

Response

A Token resource.

User Groups

The User Group Resource

Note

# include this code when using cloudify python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>',
        tenant='<manager-tenant>')

The User Group is a group of users.

Attributes:

Attribute	Type	Description
`id`	integer	Auto increment, unique identifier for the tenant.
`ldap_dn`	string	The distinguish name of corresponding LDAP group (if using LDAP).
`name`	string	The name of the user group.

List User Groups

Request Example

$ curl -X GET --header "tenant: default_tenant" -u user:password "http://<manager-ip>/api/v3/user-groups"

# Python Client-
client.user_groups.list()

Response Example

{
    "items":
        [
            {
                "ldap_dn": null,
                "tenants": [],
                "name": "new_group",
                "users": []
            }
        ]
}

GET "{manager-ip}/api/v3/user-groups"

List all user groups.

Response

Field	Type	Description
`items`	list	A list of `Group` resources.

Get User Group

Request Example

$ curl -X GET --header "tenant: default_tenant" -u user:password "http://<manager-ip>/api/v3/user-groups/<group-name>"

# Python Client-
client.user_groups.get(<group-name>)

Response Example

{
    "ldap_dn": null,
    "name": "new_group",
    "tenants": [],
    "users": []
}

GET "{manager-ip}/api/v3/user-groups/{group-name}"

Retrieves a specific group.

URI Parameters

group-name: The name of the group to retrieve.

Response

A Group resource.

Create User Groups

Request Example

$ curl -X POST -H "Content-Type: application/json" -H "tenant: default_tenant" -d '{"group_name": <group-name>, "ldap_group_dn": <optional-ldap-dn>}' -u user:password "http://<manager-ip>/api/v3/user-groups"

# Python Client-
client.user_groups.create(group_name=<group-name>, ldap_group_dn=<optional-ldap-dn>)

Response Example

{
    "ldap_dn": "group_ldap_dn",
    "name": "new_group",
    "tenants": [],
    "users": []
}

POST -d '{"group_name": <group-name>, "ldap_group_dn": <optional-ldap-dn>}' "{manager-ip}/api/v3/user-groups"

Creates a new user group.

Request Body

Property	Type	Description
`group_name`	string	The group name.
`ldap_group_dn`	string	Optional parameter, The distinguishing name of the corresponding LDAP group, if appropriate.

Response

A User resource.

Delete User Group

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/user-groups/<user-group-name-to-delete>"

# Python Client-
client.user_groups.delete(<group-name>)

Response Example

{
    "ldap_dn": "group_ldap_dn",
    "name": "new_group",
    "tenants": [],
    "users": []
}

DELETE "{manager-ip}/api/v3/user-groups/{user-group-to-delete}"

Deletes a user group.

URI Parameters

user-group-to-delete: The name of the user group to delete.

Response

A Group resource.

Add User to Group

Request Example

$ curl -X PUT -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"username": <user-name>, "group_name": <group-name>}' `"http://<manager-ip>/api/v3/user-groups/users"

# Python Client-
client.user_groups.add_user(<user-name>, <group-name>)

Response Example

{
    "ldap_dn": "group_ldap_dn",
    "name": "new_group",
    "tenants": [],
    "users": ["user_name"]
}

PUT "{manager-ip}/api/v3/user-groups/users"

Add a user to group.

Request Body

Property	Type	Description
`username`	string	The name of the user to add to the group.
`group_name`	string	The name of the group to which to add the user.

Response

A Group resource.

Remove User from Group

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"username": <user-name>, "group_name": <group-name>}' `"http://<manager-ip>/api/v3/user-groups/users"

# Python Client-
client.user_groups.remove_user(<user-name>, <group-name>)

Response Example

{
    "ldap_dn": "group_ldap_dn",
    "name": "new_group",
    "tenants": [],
    "users": ["user_name"]
}

DELETE "{manager-ip}/api/v3/user-groups/users"

Delete a user from a group.

Request Body

Property	Type	Description
`username`	string	The name of the user to remove from the group.
`group_name`	string	The name of the group from which to remove the user.

Response

A Group resource.

Users

The User Resource

Note

# include this code when using cloudify python client-
from cloudify_rest_client import CloudifyClient
client = CloudifyClient(
        host='<manager-ip>',
        username='<manager-username>',
        password='<manager-password>',
        tenant='<manager-tenant>')

Since Cloudify 4.0, Cloudify user management has been added

Attributes:

Attribute	Type	Description
`active`	boolean	Whether the user’s status is active or suspended.
`created_at`	UTCDateTime	Date on which the user was created.
`first_name`	string	The user’s first name..
`id`	integer	Auto increment, unique identifier for the tenant.
`last_login_at`	UTCDateTime	Date of last request performed by the user.
`last_name`	string	The user’s last name.
`password`	string	The user hashed password.
`username`	string	The username.

List Users

Request Example

$ curl -X GET --header "tenant: default_tenant" -u user:password "http://<manager-ip>/api/v3/users"

# Python Client-
client.users.list()

Response Example

{
 "items":
    [
        {
            "username": "admin",
            "last_login_at": "2017-01-22T15:09:33.799Z",
            "role": "administrator",
            "groups": [],
            "active": true,
            "tenants": ["default_tenant"]
        }
    ]
}

GET "{manager-ip}/api/v3/users"

List all users.

Response

Field	Type	Description
`items`	list	A list of `User` resources.

Get User

Request Example

$ curl -X GET --header "tenant: default_tenant" -u user:password "http://<manager-ip>/api/v3/users/<user-name>"

# Python Client-
client.users.get(<user-name>)

Response Example

{
    "username": "admin",
    "last_login_at": "2017-01-22T15:09:33.799Z",
    "role": "administrator",
    "groups": [],
    "active": true,
    "tenants": ["default_tenant"]
}

GET "{manager-ip}/api/v3/users/{user-name}"

Retrieves a specific user.

URI Parameters

user-name: The name of the user to retrieve.

Response

A User resource.

Create User

Request Example

$ curl -X PUT -H "Content-Type: application/json" -H "tenant: <tenant-name>" -d '{"username": <new-user-name>, "password": <password>, "role": <role>}' -u user:password "http://{manager-ip}/api/v3/users"

# Python Client-
client.users.create(<new-user-name>,
                    <password>,
                    <role>)

Response Example

{
    "username": "admin",
    "last_login_at": "2017-01-22T15:09:33.799Z",
    "role": "administrator",
    "groups": [],
    "active": true,
    "tenants": ["default_tenant"]
}

PUT -d '{"username": <new-user-name>, "password": <password>, "role": <role>}' "{manager-ip}/api/v3/users"

Creates a new user.

Request Body

Property	Type	Description
`username`	string	The username.
`password`	string	The user password.
`role`	string	The user role. One of the following: `user`, `administrator`, `suspended`.

Response

A User resource.

Delete User

Request Example

$ curl -X DELETE -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password "http://<manager-ip>/api/v3/users/<user-name-to-delete>"

# Python Client-
client.users.delete(<user-name>)

Response Example

{
    "username": "user",
    "last_login_at": "2017-01-22T15:09:33.799Z",
    "role": "user",
    "groups": [],
    "active": true,
    "tenants": ["default_tenant"]
}

DELETE "{manager-ip}/api/v3/tenants/{user-name-to-delete}"

Delete a user.

URI Parameters

user-name-to-delete: The name of the user to delete.

Response

A User resource.

Set user password

Request Example

$ curl -X POST -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"password": <new-password>}' "http://<manager-ip>/api/v3/users/<user-name>"

# Python Client-
client.users.set_password(<user-name>, <new-password>)

Response Example

{
    "username": "user",
    "last_login_at": "2017-01-22T15:09:33.799Z",
    "role": "user",
    "groups": [],
    "active": true,
    "tenants": ["default_tenant"]
}

POST -d '{"password": <new-password>}' '"{manager-ip}/api/v3/users/{user-name}"

Specify a password.

URI Parameters

user-name: The name of the user whose password is to be changed.

Request Body

Property	Type	Description
`password`	string	The new user password.

Response

A User resource.

Set user role

Request Example

$ curl -X POST -H "Content-Type: application/json" -H "tenant: <tenant-name>" -u user:password -d '{"role": <user-role>}' "http://<manager-ip>/api/v3/users/<user-name>"

# Python Client-
client.users.set_role(<user-name>, <new-role>)

Response Example

{
    "username": "user",
    "last_login_at": "2017-01-22T15:09:33.799Z",
    "role": "user",
    "groups": [],
    "active": true,
    "tenants": ["default_tenant"]
}

POST -d '{"role": <role>}' '"{manager-ip}/api/v3/users/{user-name}"

Set a new role for the user (user, administrator, suspended).

user - The default user.
administrator - Can execute Cloudify management commands (handle users, tenants, etc)
suspended - Prevents user access to Cloudify, without deleting them.

URI Parameters

user-name: The name of the user whose role is to be set.

Request Body

Property	Type	Description
`role`	string	The user role. One of the following: `user`, `administrator`, `suspended`.

Response

A User resource.