Cisco Virtual Application Cloud Segmentation Services REST ...€¦ · Cisco Systems, Inc. 1 Cisco Virtual Application Cloud Segmentation Services REST API Guide, Release 5.5STV3.1

Cisco Systems, Inc. www.cisco.com

1

Cisco Virtual Application Cloud

Segmentation Services REST API Guide,

Release 5.5STV3.1 First Published: 2016-08-08

Last Updated: 2016-09-08

Cisco Virtual Application Cloud Segmentation Services REST API Guide, Release 5.5STV3.1

Overview

2

Contents Overview ............................................................................................................................................................................ 5

About the Cisco VACS REST API ..................................................................................................................................... 5

Access Privileges ............................................................................................................................................................ 5

Supported Protocols and Formats ................................................................................................................................. 5

Recommended Tools ..................................................................................................................................................... 6

Poodle Vulnerability ...................................................................................................................................................... 6

Getting Started .................................................................................................................................................................. 7

About the API Access Key .............................................................................................................................................. 7

Generating an API Access Key ........................................................................................................................................ 7

Enabling the Developer Menu Options ......................................................................................................................... 7

Using the REST API Browser ........................................................................................................................................... 8

Prerequisites .............................................................................................................................................................. 8

Accessing the Report Metadata ..................................................................................................................................... 9

Prerequisites .............................................................................................................................................................. 9

Request Format ............................................................................................................................................................. 9

Response Format ......................................................................................................................................................... 11

REST Tools ........................................................................................................................................................................ 13

REST API Browser ......................................................................................................................................................... 13

Usage Example: Retrieving the VM Summary ......................................................................................................... 13

Usage Example: Creating a Group ........................................................................................................................... 14

Usage Example: Sample Java Code .......................................................................................................................... 16

REST API SDK Bundle .................................................................................................................................................... 17

About the REST API Operations ....................................................................................................................................... 18

Cisco VACS Container Operations .................................................................................................................................... 18

userAPIGetContainerDetails ........................................................................................................................................ 18

userAPIGetTemplate .................................................................................................................................................... 20

userAPIVACSCreateContainerRest ............................................................................................................................... 23

userAPIGetTemplateNameAndType ............................................................................................................................ 43

userAPIVACSOptionsMenu .......................................................................................................................................... 44

userAPIGetOptionsMenu ............................................................................................................................................. 44

userAPIGetStaticNAT ................................................................................................................................................... 45


Overview

3

userAPIGetStaticNATPerVM ........................................................................................................................................ 45

userAPIVACSSetNat ..................................................................................................................................................... 46

userAPIGetERSPAN ...................................................................................................................................................... 47

userAPIVACSsetErspan ................................................................................................................................................ 48

userAPIGetERSPANWithVM ......................................................................................................................................... 49

userAPIVACSaddVM ..................................................................................................................................................... 50

userAPIVACSdeleteVM ................................................................................................................................................ 51

userAPIVACSPowerOnContainer ................................................................................................................................. 52

userAPIVACSPowerOffContainer ................................................................................................................................. 53

userAPIGetVACSResourceHistory ................................................................................................................................ 54

userAPIGetContainerVmIps ......................................................................................................................................... 63

userAPIVACSaddVM(with password sharing options) ................................................................................................. 63

userAPIGetFirewallPolicy ............................................................................................................................................. 65

userAPIVACSManageFirewallPolicyAclRule (Add Firewall Policy) ............................................................................... 66

userAPIVACSManageFirewallPolicy (Update Firewall Policy) ...................................................................................... 67

userAPIVACSManageFirewallPolicyAclRule (Delete Firewall Policy) ........................................................................... 68

userAPIGetServiceVMPasswords ................................................................................................................................. 70

ServiceVMPassword..................................................................................................................................................... 71

userAPIGetZones ......................................................................................................................................................... 72

userAPIGetZonesWithVM ............................................................................................................................................ 73

userAPIVACSManageZones .......................................................................................................................................... 74

userAPIVACSManageZones (Add Zones) ................................................................................................................. 74

userAPIVACSManageZones (Delete Zones) ............................................................................................................. 76

userAPIGetReservationInfo ......................................................................................................................................... 76

userAPIGetManageVMNetwork .................................................................................................................................. 77

userAPIVACSManagenetwork ...................................................................................................................................... 78

userAPIVACSManagenetwork (Add VM Network) .................................................................................................. 78

userAPIVACSManagenetwork (Delete VM Network) .............................................................................................. 80

VACSManagenetworkGarbageCollection .................................................................................................................... 80

Script Operations ......................................................................................................................................................... 81

userAPIExecuteVIXScript .......................................................................................................................................... 81

Understanding Workflows ............................................................................................................................................... 81

Workflow Designer ...................................................................................................................................................... 82


Overview

4

Predefined Tasks .......................................................................................................................................................... 83

Predefined Workflows ................................................................................................................................................. 83

Cisco VACS Workflows ................................................................................................................................................. 83

Creating a Workflow .................................................................................................................................................... 83

Adding Tasks to a Workflow ........................................................................................................................................ 84

Linking Tasks ................................................................................................................................................................ 85

Accessing the Task Documentation ............................................................................................................................. 85

Sample Custom Tasks or Workflows ................................................................................................................................ 85

Adding a Custom Task to an Existing Workflow ...................................................................................................... 85

Code Snippets .................................................................................................................................................................. 92

1. How to get the list of catalog items for a given group? ...................................................................................... 94

2. How to order a Cisco VACS container based on the catalog items? ................................................................... 94

3. How to view a container details? ........................................................................................................................ 95

4. How to get the status of a service request? ........................................................................................................ 96

5. How to execute VM life-cycle operations on a workload VM? ........................................................................... 98

6. How to get the status of workload VMs? ............................................................................................................ 99

7. How to get the StaticNAT information for a container? .................................................................................... 100

8. How to add a workload VM to a container? ...................................................................................................... 101

9. How to delete a workload VM in a container? .................................................................................................. 103

Obtaining Documentation and Submitting a Service Request ...................................................................................... 104

Related Documentation ................................................................................................................................................. 104


Overview

5

Overview This section includes the following topics:

About the Cisco VACS REST API

Access Privileges

Supported Protocols and Formats

Recommended Tools

POODLE Vulnerability

About the Cisco VACS REST API

The Cisco VACS REST API enables you to perform operations on the Cisco UCS Director resources and to integrate

these operations into applications so that they can provide API-supported functionality and features. You can use

applications developed using this REST (Representational State Transfer) API to do the following:

Get Cisco UCS Director reports about physical and virtual devices, networks, appliances, groups and users,

policies, administration, resource accounting, funds, and other monitored entities within your Cisco UCS

Director.

Invoke orchestrator workflow and task operations.

Invoke additional operations specific to Cisco UCS Director.

Attention: For all Cisco UCS Director API Operations such as managing groups, catalogs, virtual machines, and the

corresponding operations see the Cisco UCS Director REST API Cookbook.

Access Privileges

With appropriate access privileges, you can use the APIs to get any report made available through Cisco UCS Director.

Access to the API interface is limited to registered user accounts. Secure access is administered through the use of the

REST API Access Key, which is a unique key code assigned to each user account. A user account is administratively

associated with a user type, so this access key determines the user account's level of access to information exposed

through the API.

Different user types have access to different categories of data. A Cisco UCS Director administrator defines the access

rules associated with each user type. For more information on the end-user and administrator user types and the data

accessible to each type of user, see the http://www.cisco.com/c/en/us/support/servers-unified-computing/ucs-

director/products-maintenance-guides-list.html or contact your system administrator. Work with your system

administrator to get the necessary user access privileges for your project.

Supported Protocols and Formats

Cisco VACS REST APIs are compatible with any HTTP or HTTPS browser. The REST APIs use code formatted in JSON

and XML. A Java API is also available.

JSON

Unless otherwise noted, the Cisco UCS Director API documentation refers to REST API request arguments and

responses (payload data) that are encoded in JSON (JavaScript Object Notation) format. For more information, see http:/

/www.json.org or http://en.wikipedia.org/wiki/JSON.

Note

Live and valid Cisco VACS REST API requests and responses in JSON format are provided within Cisco UCS Director.

These provide excellent examples of JSON protocols and formatting. To see this API data, you must first enable the

developer menus and then use the Report Metadata option available on any report in Cisco UCS Director. For more

information, see Enabling the Developer Menu Options.

http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/ucs-director/rest-api-cookbook/5-5/b_Cisco_UCS_Director_REST_API_Cookbook_55.htmlhttp://www.cisco.com/c/en/us/support/servers-unified-computing/ucs-director/products-maintenance-guides-list.htmlhttp://www.cisco.com/c/en/us/support/servers-unified-computing/ucs-director/products-maintenance-guides-list.htmlhttp:///www.json.orghttp:///www.json.orghttp:///en.wikipedia.org/wiki/JSON


Overview

6

XML

For information about using XML-formatted REST API requests, see Using the REST API Browser. This provides

information about using the REST API browser, which is embedded in Cisco UCS Director.

Java

For information about using the Java API, see the Cisco UCS Director REST API Javadocs and the Cisco UCS Director

Open Automation API Javadocs.

Recommended Tools

The Cisco VACS API uses HTTP or HTTPS as communication protocols. Any compatible browser or client with user

account access can be used to submit requests to the Cisco VACS API. Most programming languages have built-in or

open source libraries that provide REST API access and parsing of JSON and XML.

For exploring and testing the APIs, we recommend the following software tools and options:

Developer Menu Options

Cisco UCS Director includes Developer Menu options that include crucial features and tools for developers, such as

Report Metadata and access to the Rest API Browser. To enable these options, see Accessing the Report Metadata.

Mozilla Firefox RESTClient Add-On

RESTClient is a Mozilla FireFox add-on that provides useful options for parsing and viewing API requests and responses.

See https://addons.mozilla.org/en-US/firefox/addon/restclient/?src=ss, but check for more recent releases.

Note

If you are currently logged into Cisco UCS Director with user account credentials that your application will use, you

should be able to use any supported web browser to send API requests and get responses. However, the Mozilla Firefox

RESTClient add-on provides a standalone client that also parses and labels the API data in a useful and informative way.

Cisco UCS Director REST API Browser

The REST API Browser is available in the Orchestration area of Cisco UCS Director. It provides API information and API

code generation capabilities that make it easy to see and work with all of the available APIs, including both the REST

APIs and the Java API.

After you enable the developer menu, you can access this feature and get extensive information about Cisco UCS

Director exposed APIs, including the REST API in XML format and the Java API. For more information, see Using the

REST API Browser.

Poodle Vulnerability

To avoid POODLE vulnerability, SSL Version 2 and SSL Version 3 are disabled on Cisco UCS Director north-bound HTTP

interface by configuring Apache Tomcat to allow only TLS. Hence, any north-bound applications accessing Cisco UCS

Director through REST API will be connected through TLS. Also, the browsers will be connected to Cisco UCS Director

through TLS. For more information, refer http://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-

sa-20141015-poodle.

http://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-20141015-poodlehttp://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-20141015-poodle


Getting Started

7

Getting Started This section includes the following topics:

About the API Access Key

Generating and API Access Key

Enabling the Developer Menu Options

Using the REST API Browser

Request Format

Response Format

About the API Access Key

To access Cisco UCS Director through the API interface, you must have a valid Cisco UCS Director user account and an

API access key. The API access key is required for Cisco UCS Director to authenticate API requests. This access key is a

unique security access key code that is associated with a specific valid Cisco UCS Director user account.

To authenticate API requests, all Cisco UCS Director APIs require the API access key for authentication. You must pass

the REST API access key as a name:value header following standard HTTP syntax and semantic rules. For example, a

valid name:value header is X-Cloupia-Request-Key: F90ZZF12345678ZZ90Z12ZZ3456FZ789. For more information

about the API request header, see Request Format and RFC2616 Header Field Definitions.

To provide data security, send all requests over an HTTPs (SSL) connection.

Generating an API Access Key

To generate the API access key, perform the following steps:

______________________________________________________________________________________________

Step 1: In Cisco UCS Director, click your login name in the upper right.

For example, if you log in as admin, Cisco UCS Director displays admin in the upper right.

Step 2 In the User Information dialog box, click the Advanced tab.

Step 3 To copy the value displayed in the REST API Access Key area, click Copy Key Value.

Step 4 Save the access key in a secure location, and use it in the API request header.

For more information about the API request header, see Request Format.

Step 5: If you want to change the API access key, click Regenerate Key.

After you generate a new key, the old key code is retired and you cannot use it.

______________________________________________________________________________________________

Enabling the Developer Menu Options

Cisco UCS Director includes features and capabilities that are intended expressly for developers and engineers. After

you enable the Developer Menu option, you have access to the integrated REST API Browser and Report Metadata

information. These features provide you with site-specific API data and with REST API request code that you can send

through any standard HTTP or HTTPS browser. The HTTP request code provided by the Report Metadata views yields

immediate API service results. Plan to use these options in every situation where you need API information.

Obtain one or more user accounts that provide exactly the same administrative access to data that your application users

will have. Your Cisco UCS Director administrator can explain the data access limitations associated with different

administrator and end-user roles. You may want multiple user accounts to test the user-experiences associated with

different data access and security controls.

The Cisco UCS Director REST API Browser provides API information and API code generation capabilities that make it

easy to see and work with all of the available APIs, including both the REST APIs and the Java APIs.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html


Getting Started

8

To enable end menu options, perform the following steps:

_______________________________________________________________________________________________

Step 1: In Cisco UCS Director, click your login name in the upper right.

For example, if you log in as admin, Cisco UCS Director displays admin in the upper right.

Step 2 In the User Information dialog box, click the Advanced tab.

Step 3 Check the Enable Developer Menu (for this session) check box and close the User Information dialog box.

The REST API Browser is activated for the duration of the current session, and the Report Metadata option

becomes available in the report views opened in the session.

Note

The Advanced tab also displays the REST API Access Key code for the account.

Step 4 Close the User Information dialog box.

_______________________________________________________________________________________________

Using the REST API Browser

The Cisco UCS Director REST API Browser provides API information and API code generation capabilities that assist and

educate developers in the use of all available exposed Cisco UCS Director APIs, including the XML-formatted REST API

and the Java API. The primary view lists the Task folders, each of which provides access to the APIs. The task name

effectively supplies the top-level context or category folder under which the APIs are listed. For example, all the APIs

pertaining to NetApp ONTAP tasks and NetApp OnCommand tasks are available inside the folders with these names.

Prerequisites

1. Obtain one or more user accounts that provide exactly the same administrative access to data that your application users

will have. Your Cisco UCS Director administrator can explain the data access limitations associated with different

administrator and end-user roles. You may want multiple user accounts to test the user-experiences associated with

different data access and security controls.

2. Enable the developer menu option for the session.

To use the REST API browser, perform the following steps:

Step 1: On the menu bar, choose Policies > Orchestration.

Step 2 Click the REST API Browser tab.

Click the right scroll arrow, if necessary, to navigate to the REST API Browser tab.

Step 3 Open the task folder that contains the APIs you want to view.

Notes:

1. You can use the Search field at the top right corner of the Rest API Browser tab to find a specific API if you

do not know which task folder it belongs in. Enter a string that occurs in the API Resource, Operation or

Description fields to narrow your search. You can also use the other options on that menu bar, such as the

Add Advanced Filter, to help you find a specific API.

2. All Cisco VACS REST APIs are available in the Service Container Tasks group.

Step 4 Double-click a row that contains an API resource and operation that interests you.

The REST API browser displays the following:

API Examples tab Displays the API data for your selection and enables you to generate a sample URL.

Depending on the operation and resource that you selected, this tab might also include data entry

boxes that accept parameter values and enable you to construct a successful API request. If available in

a data entry box, click Select to open data search filters that can help you sort out and select the data

that you need to enter.

Details tab Provides additional details about the API, including the API definition, input parameters, and

output parameters.

Sample Java Code tab Provides sample code for the API.

_________________________________________________________________________________________________


Getting Started

9

Accessing the Report Metadata

Report Metadata enables you to view the API code used by Cisco UCS Director, including the API request code for every

report displayed in Cisco UCS Director. This code includes complete URL code that is ready to paste into a browser and

send. The immediate API responses provide a trove of information and education for the developer. To see the API

request code, you simply navigate to a report, select Report Metadata, and scroll down through the resulting list to the

API request used to fetch the report.

Prerequisites Obtain one or more user accounts that provide exactly the same administrative access to data that your application

users will have. Your Cisco UCS Director administrator can explain the data access limitations associated with

different administrator and end-user roles. You may want multiple user accounts in order to test the user-

experiences associated with different data access and security controls.

Enable the Developer Menu options for the session.

To access the report metadata, perform the following steps:

_________________________________________________________________________________________________

Step 1: In Cisco UCS Director, navigate to the page for which you want to see the API code.

For example, choose one of the following:

Policies > Orchestrations

Physcial > Storage > Storage_Account >Filers

Step 2: Check Report Metadata.

Step 3: In the Information dialog box, review the sample code.

_________________________________________________________________________________________________

Request Format

API clients can use HTTP or HTTPS to interact with Cisco UCS Director. To pass the REST API access key, each request

must be associated with an http/https header called X-Cloupia-Request-Key with its value set to the current REST API

Access Key. For information about getting and using this key, see Generating an API Access Key.

URL Format

http://SERVER/app/api/rest?formatType=json&opName=operationName&opData=operationData

where SERVER is the IP address or the hostname of the Cisco UCS Director VM, and where opName is the API operation

name associated with the request. For example: userAPIGetMyLoginProfile, or userAPIGetVMActionStatus, and where

opData includes the JSON parameters (the arguments associated with the operation).

Request URL Parameters

formatType The only supported format that is discussed here is JavaScript Object Notation (JSON). Set this

parameter value to json.

opName The operation name associated with the request. A list of operations is provided in About the REST

API Operations.

opData Parameters (or arguments) associated with the operation. Cisco UCS Director uses JSON encoding of

the parameters. If no arguments are required for the operation, use {} as an empty set. Before you send JSON

data in a request, you must apply escape characters as appropriate. For details about encoding the URL, see the

RFC at http://www.ietf.org/rfc/rfc1738.txt.

For more information about JSON syntax and data types, see

https://en.wikipedia.org/wiki/JSON#Data_types.2C_syntax_and_example.

For information about non-JSON formatted API requests, see Using the REST API Browser.

About Operations Data Parameters/Arguments

http:///www.ietf.org/rfc/rfc1738.txthttps://en.wikipedia.org/wiki/JSON#Data_types.2C_syntax_and_example


Getting Started

10

Because the method and a generic designation of the API resource are communicated through the opName, the

operation parameters must present any arguments that are needed to designate a specific instance of the resource to be

operated upon.

For a list of available API operations and parameter specifications, see About the REST API Operations.

Operations Data Parameter Syntax

The following table shows examples of operations data parameter syntax in JSON format.

If the operation needs the following parameters

(opData)

How to represent in JSON

No parameters {}

One parameter; integer (for example, 10) {param0:10}

One parameter: string (for example, cloud) {param0:"cloud"}

Two parameters: a string and an Integer {param0:"cloud",param1:10}

Two parameters: a string with null value and an Integer {param0:null,param1:10}

Three parameters {param0:"cloud",param1:"cloupia",param2:100}

Operation Data Parameters ",param2:"STORAGE-ACCOUNTS-T51"

opData= {param0:"Create NFS Datastore",param1:{"list":[{"name":"Volume

Size","value":100},{"name":"Select Group","value":"14"},{"name":"Select vDC","value":18}]},param2:212}

param0 Name of the workflow being invoked through the REST API.

param1 Input being passed to the workflow. If there are more than one input, separate the inputs by comma and

within the curly braces with proper quotations. If there are no inputs, use null for the API invocation.

param2 If this workflow is being invoked as a child workflow of another service request, use the service request

(SR) ID. If this workflow is not invoked as a child workflow, use -1. When -1 is used, a new service request will be

invoked.

Note: Cisco UCS Director provides many complete API requests, formatted as URLs and ready for you to cut and paste into a

browser. See Enabling the Developer Menu Options.

Context Parameters

In the example above, Param0 is used to specify the Cisco UCS Director context. The context data value refers to one of the

major domains managed by Cisco UCS Director, for example, "global-services", "vm", "vdc", "datacenter",

"storage_accounts", "Compute-chassis", "network-device". A list of the standard Cisco UCS Director contexts appears in

API Request Context Parameters.

Report Parameters

The report parameter value is always the reportId. Typical reportIds include "STORAGE-ACCOUNTS-T51", "CPU-S0",

"VOLUMES--X1", "NETWORK-USAGE-H0", "PORT-SUMMARY-V50", "PRIVATE-CLOUD-FREE-STORAGE-S1". The

reportId is typically the last parameter listed in an API request for a report. So, if the context is specified by two parameters,

the report parameter is often the third, param2. For an extensive list of report names, and reportIds, categorized by context,

see List of Available Cisco UCS Director Reports.

Sample API Request 1 The operation that requests a Login profile refers to the logged in user, so there is no need for a parameter. Most other

operations need multiple arguments.

http://10.10.1.153/app/api/rest?formatType=json&opName=userAPIGetMyLoginProfile&opData={}


Getting Started

11

{ "serviceResult":{"userId":"jsmith","firstName":"John","lastName":"Smith","email":"[email protected]",

"groupName":"Eng Group","role":"Regular"}, "serviceError":null,

"serviceName":"InfraMgr", "opName":"userAPIGetMyLoginProfile" }

Sample API Request 2

In this request for a report about chassis for a data center, the operation requires three parameters, which is typical for a

report request.

http://172.99.999.142/app/api/rest?opName=userAPIGetTabularReport&opData={param0:"datacenter",

param1:"datacenter",param2:"UCS-CHASSIS-T50"}

{ "serviceResult":

{"rows":[{"ID":"PHY-ACC;sys/chassis-2",

"Account_Name":"PHY-ACC","DN":"sys/chassis-2",

"Serial_Number":"1558","Model":"N20-C6508","Power_State":"ok",

"Operation_State":"accessibility-problem",

"Configuration_State":"ok","License_State":"license-ok","Servers":5,

"IO_Modules":2,"PSUs":4,"Fan_Modules":8,

"Vendor":"Cisco Systems Inc"},{"ID":"UCSCirrus;sys/chassis-1",

"Account_Name":"UCSCirrus","DN":"sys/chassis-1",

"Serial_Number":"FOX1352GDX4","Model":"N20-C6508",

"Power_State":"redundancy-failed","Operation_State":"power-problem",

"Configuration_State":"ok","License_State":"license-ok","Servers":7,

"IO_Modules":2,"PSUs":4,"Fan_Modules":8,

"Vendor":"Cisco Systems Inc"},{"ID":"UCSM237;sys/chassis-1",

"Account_Name":"UCSM237","DN":"sys/chassis-1",

"Serial_Number":"1557","Model":"N20-C6508","Power_State":"ok",

"Operation_State":"operable",

"Configuration_State":"unsupported-connectivity","License_State":"license-ok",

"Servers":6,"IO_Modules":2,

"PSUs":4,"Fan_Modules":8,"Vendor":"Cisco Systems Inc"},

{"ID":"real108;sys/chassis-1","Account_Name":"real108",

"DN":"sys/chassis-1","Serial_Number":"FOX1352GDX4","Model":"N20-C6508",

"Power_State":"redundancy-failed",

"Operation_State":"power-problem","Configuration_State":"ok",

"License_State":"license-ok","Servers":7,

"IO_Modules":2,"PSUs":4,"Fan_Modules":8,"Vendor":"Cisco Systems Inc"}],

"columnMetaData":null}, "serviceError":null, "serviceName":"InfraMgr",

"opName":"userAPIGetTabularReport" }}

Note: For advanced Cisco UCS Director API users, the code in the Report Metadata request for the data center's UCS-

CHASSIS-T50 report gave the first parameter as param0:"23". In the request used in Sample API Request 2, the context

"datacenter" was substituted for the value "23" and the request was successful. By comparing the API documentation

against the Report Metadata and Cisco UCS Director, you can sometimes discover alpha string value substitutes for the

numeral string values (representing contexts) that appear in the Report Metadata requests.

Response Format

The following HTTP status codes are returned by Cisco UCS Director:

401 Unauthorized The API key is not a valid key.


Getting Started

12

200 OK Cisco UCS Director has processed the request. The actual status of the request is in the body of the

response.

The Cisco UCS Director response body is in JSON format as determined by the FormatType parameter specified in the API

request.

Components of an API Response

API Response Component Description Component Example (Success Scenario)

serviceResult If the request succeeds, this result

contains a specified set of name-

value pairs or a JSON object or a

report.

"serviceResult":

{"userId":"jsmith",

"firstName":"John","lastName":"Smith",

"email":"[email protected]",

groupName":"Eng Group","role":"Regular"}

serviceError If the request succeeds, the

serviceError is set to null. If the

operation fails, the serviceError

contains the actual error message.

"serviceError":null

serviceName Name of the back end service. Often

set to InfraMgr, for example.

"serviceName":"InfraMgr"

opName Name of the operation provided in

the request.

"opName":"userAPIGetMyLoginProfile"

Example: API Response in a Success Scenario

{ "serviceResult":{"userId":"jsmith","firstName":"John","lastName":"Smith",

"email":"jsmith@example.

com","groupName":"Eng Group","role":"Regular"}, "serviceError":null, "serviceName":"InfraMgr",

"opName":"userAPIGetMyLoginProfile"

}

Example: API Response in a Failure Scenario

{ "serviceResponse":null, "serviceError":"SERVICE_CALL_EXCEPTION: Service InfraMgr does not support operation test",

"serviceName":"InfraMgr", "opName":"test"

}

API Response (Service Result) Data Types

The service result (payload) sent in a response to a Cisco VACS REST API request is specified for the operation. The service

result can be an operation-specific set of name-value pairs, or it can be formatted as a standard data type for this API, that

is, as a report or a JSON object.

To see examples of the different report types, see Reports and JSON Object Response Samples.

For information about the most commonly used Cisco UCS Director report formats and their contents, see About Reports.

For a list of available reports and the contexts with which they are associated, see List of Available Cisco UCS Director

Reports.


REST Tools

13

For samples of JSON Objects, see JSON Object Parameter Types.

REST Tools By default, Cisco VACS is enabled to respond to the REST API requests from the appropriate REST clients. Cisco VACS

provides the following entities to aid in the REST API developments:

REST API Browser

REST API SDK Bundle

REST API Browser

The REST API browser available with Cisco UCS Director aids the Developers and QA Engineers to validate the REST

APIs added to the framework.

An administrator or group administration user can launch the REST API Browser. To launch the REST API Browser,

choose Policies > Orchestration > REST API Browser.

The REST API browser groups the APIs based on the tasks needed to manage the respective infrastructure components

of the datacenter.

To view an API, expand a task folder and double-click the report for the respective API. The browser provides the

following tabs for the selected API:

1) API Examples Displays the inputs for user-selection. A Developer can provide his inputs for the respective API as

required and generate a sample URL.

2) Details Defines the syntax and the semantics for the API.

3) Sample Java Code A Java code snippet that demonstrates the use of the API.

Usage Example: Retrieving the VM Summary

1. From the Cisco UCS Director menu bar, choose Policies > Orchestration > REST API Browser.

2. Select and double-click the userAPIGetVMSummary API. The following tabs are displayed:


REST Tools

14

a. API Examples

b. Details

c. Sample Java Code

3. Click the Details tab, to view the definition of the userAPIGetVMSummary API. The userAPIGetVMSummary API

takes the vmId as its input.

4. In the API Examples tab, click Generate URL to get the URL for the REST operation. The vmId must be passed as

the param0, as shown in the following dialog box.

5. From the UCSD Server drop-down list, choose Cisco UCS Director on which the API is targeted at and click

Execute REST API for a response.

Usage Example: Creating a Group



a. API Examples

b. Details

c. Sample Java Code

3. Click the Details tab, to view the definition of the userAPIGetVMSummary API. The userAPIGetVMSummary API

takes the vmId as its input.


REST Tools

15

4. In the API Examples tab, click Generate URL to get the URL for the REST operation. The vmId must be passed as

the param0, as shown in the following dialog box.



Upon clicking Execute REST API, the following screen appears.

6. Fill in the fields and click Generate XML to generate the sample XML file for group creation.


REST Tools

16



Usage Example: Sample Java Code



a. API Examples

b. Details

c. Sample Java Code

The Sample Java Code tab provides the code snippet that can be used to automate the management services through

code.

The code snippet can be used to execute the respective API. To execute the code in the Eclipse and obtain the output,

you must import the SDK bundle as a Java Project into the Eclipse IDE.

To import the SDK bundle, perform the following steps:

______________________________________________________________________________________________

1. In the Eclipse IDE, choose File > New > Java Project. The Create a Java Project dialog box appears.

2. In the Project Name field, enter a name for the project.

3. Right click the project, and select Import.

4. In the Import dialog box, select Existing projects into Workspace, and then click Next.

5. Click Browse and navigate to the folder where you extracted the SDK Bundle.


REST Tools

17

6. Click Finish.

The Eclipse IDE displays the SDK Bundle project on the Project Explorer tab.

_________________________________________________________________________________________________

REST API SDK Bundle

For more information on the REST API SDK bundle, see the Cisco UCS Director REST

API Developer Guide.

http://www.cisco.com/c/en/us/support/servers-unified-computing/ucs-director/products-programming-reference-guides-list.htmlhttp://www.cisco.com/c/en/us/support/servers-unified-computing/ucs-director/products-programming-reference-guides-list.html


About the REST API Operations

18

About the REST API Operations The catalog of Cisco VACS REST API operations provided in this section can help you determine which operations serve

your needs, and how to work with each operation. You can find examples of the request and response values for an API

operation through the Report Metadata and REST API Browser.

Note:

The operations performed using the GET and PUT method are used primarily for services and provisioning.

The opData of the API request URL, includes the following JSON parameters (the arguments associated with the

operation):

o param0 Name of the workflow being invoked through the REST API.

o param1 Input being passed to the workflow. If there are more than one input, separate the inputs by

comma and within the curly braces with proper quotations. If there are no inputs, use null for the API

invocation.

o param2 If this workflow is being invoked as a child workflow of another service request, use the

service request (SR) ID. If this workflow is not invoked as a child workflow, use -1. When -1 is used, a

new service request will be invoked.

Cisco VACS Container Operations

userAPIGetContainerDetails

Method

GET

Resource URL

http://< UCSD IP Address

>/app/api/rest?formatType=json&opName=vacs:userAPIGetContainerDetails&opData={param0:}

Description

Fetches the VACS container details such as, VM name, ID, IP and MAC addresses, and so on.

Sample URL

https:///app/api/rest?formatType=json&opName=vacs:userAPIGetContainerDetails&opData={param0:36}

Parameters

Integer Container ID

Accessible

Administrator

Example

Response Header: Status Code: 200 OK

Cache-Control: max-age=0,must-revalidate Content-Length: 5418

Content-Type: application/json;charset=UTF-8

Date: Mon, 16 Feb 2015 22:17:06 GMT Expires: -1

Server: Apache-Coyote/1.1

Set-Cookie: JSESSIONID=ECD2F3737D8D3C75805A8FC4FE702404; Path=/app/; Secure



19

Response Body:

{ "serviceResult": "[{"vmId":152,"instanceId":"CUST2-primary-csr","accountName":"Adi-

VC","hostName":"CUST2-primary-

71","ipAddress":"172.23.233.100","parentHost":"172.23.233.53","powerStatus":"ON","status":"poweredOn","imageId":"CUST2-primary-

csr","lastUpdated":1424123027736,"isArchived":false,"groupId":1,"serviceRequestId":71,"userLabel":"",

"comments":"","provisionedTime":1419561145609,"scheduledTerminationTime":-1,"catalogId":-1,"vdcId":36,"appCategoryId":0,"groupName":"Default

Group","vdcName":"CUST2","isUpdatePending":false,"pendingAction":"","vmType":"VMWare","vmUniqueId":"5

02b64ef-f200-56c5-cd6e-d26a24eb5530","committedDiskGB":3.98,"uncommittedDiskGB":6.6,"cpuReservationMhz":0,"memReservationMB"

:0,"numCPUs":1,"memoryMB":2560,"hostCPUHz":2133408810,"vmMacAddr":"00:50:56:ab:73:76,00:50:56:ab:59:6

0,00:50:56:ab:36:3c","vmwareDatacenterName":"Aditya-DC","hostUniqueId":"5ac69ba1-3159-11df-ad0a-68efbdf6214a","guestOS":"Other 2.6.x Linux (64-bit)"},{"vmId":153,"instanceId":"CUST2_WebZone_web-

1","accountName":"Adi-VC","hostName":"CUST2WebZoneweb-

1","ipAddress":"30.30.30.34","parentHost":"172.23.233.53","powerStatus":"ON","status":"poweredOn","imageId":"CUST2_WebZone_web-

1","lastUpdated":1424123027736,"isArchived":false,"groupId":1,"serviceRequestId":71,"userLabel":"CUST

2_WebZone_web-1","comments":"CUST2_WebZone_web-1","provisionedTime":1419561180868,"scheduledTerminationTime":-1,"catalogId":-

1,"vdcId":36,"appCategoryId":0,"groupName":"Default

Group","vdcName":"CUST2","isUpdatePending":false,"pendingAction":"","vmType":"VMWare","vmUniqueId":"502b3506-08ea-3004-e828-

4bc42e79a6f7","committedDiskGB":0.45,"uncommittedDiskGB":0.54,"cpuReservationMhz":0,"memReservationMB

":0,"numCPUs":1,"memoryMB":256,"hostCPUHz":2133408810,"vmMacAddr":"00:50:56:ab:56:5d","vmwareDatacenterName":"Aditya-DC","hostUniqueId":"5ac69ba1-3159-11df-ad0a-68efbdf6214a","guestOS":"Red Hat

Enterprise Linux 4 (32-bit)"},{"vmId":154,"instanceId":"CUST2-primary-vsg","accountName":"Adi-

VC","ipAddress":"172.23.233.111","parentHost":"172.23.233.53","powerStatus":"ON","status":"poweredOn","imageId":"CUST2-primary-

vsg","lastUpdated":1424123027736,"isArchived":false,"groupId":1,"serviceRequestId":71,"userLabel":"",

"comments":"","provisionedTime":1419561272698,"scheduledTerminationTime":-1,"catalogId":-1,"vdcId":36,"appCategoryId":0,"groupName":"Default


02bac85-e408-9e83-11c8-ece2dfc37e84","committedDiskGB":0.41,"uncommittedDiskGB":2.67,"cpuReservationMhz":1000,"memReservatio

nMB":2048,"numCPUs":1,"memoryMB":2048,"hostCPUHz":2133408810,"vmMacAddr":"00:50:56:ab:6f:2b,00:50:56:

ab:2e:56,00:50:56:ab:53:b4","vmwareDatacenterName":"Aditya-DC","hostUniqueId":"5ac69ba1-3159-11df-ad0a-68efbdf6214a","guestOS":"Other 2.6.x Linux (64-

bit)"},{"vmId":155,"instanceId":"CUST2_WebZone_AddedVM-1","accountName":"Adi-

VC","hostName":"CUST2WebZoneAddedVM-1","ipAddress":"30.30.30.36","parentHost":"172.23.233.53","powerStatus":"ON","status":"poweredOn","im

ageId":"CUST2_WebZone_AddedVM-

1","lastUpdated":1424123027736,"isArchived":false,"groupId":1,"serviceRequestId":72,"userLabel":"CUST2_WebZone_AddedVM-1","comments":"CUST2_WebZone_AddedVM-

1","provisionedTime":1419563334908,"scheduledTerminationTime":-1,"catalogId":-

1,"vdcId":36,"appCategoryId":0,"groupName":"Default Group","vdcName":"CUST2","isUpdatePending":false,"pendingAction":"","vmType":"VMWare","vmUniqueId":"5

02bfeac-9603-82f4-a439-

6c0449c1659f","committedDiskGB":2.01,"uncommittedDiskGB":0.07,"cpuReservationMhz":0,"memReservationMB":0,"numCPUs":1,"memoryMB":1024,"hostCPUHz":2133408810,"vmMacAddr":"00:50:56:ab:6b:a7","vmwareDatacen

terName":"Aditya-DC","hostUniqueId":"5ac69ba1-3159-11df-ad0a-68efbdf6214a","guestOS":"Red Hat

Enterprise Linux 4 (32-bit)"},{"vmId":156,"instanceId":"CUST2_AppZone_ADDAPP-1","accountName":"Adi-VC","hostName":"CUST2AppZoneADDAPP-

1","ipAddress":"30.30.30.37","parentHost":"172.23.233.53","powerStatus":"ON","status":"poweredOn","im

ageId":"CUST2_AppZone_ADDAPP-1","lastUpdated":1424123027736,"isArchived":false,"groupId":1,"serviceRequestId":73,"userLabel":"CUST

2_AppZone_ADDAPP-1","comments":"CUST2_AppZone_ADDAPP-

1","provisionedTime":1419566361783,"scheduledTerminationTime":-1,"catalogId":-1,"vdcId":36,"appCategoryId":0,"groupName":"Default


02b3c14-f151-8cc7-4f95-4e95f8c9828b","committedDiskGB":2.01,"uncommittedDiskGB":0.07,"cpuReservationMhz":0,"memReservationMB

":0,"numCPUs":1,"memoryMB":1024,"hostCPUHz":2133408810,"vmMacAddr":"00:50:56:ab:34:f2","vmwareDatacen

terName":"Aditya-DC","hostUniqueId":"5ac69ba1-3159-11df-ad0a-68efbdf6214a","guestOS":"Red Hat

Enterprise Linux 4 (32-bit)"}]",

"serviceError": null,



20

"serviceName": "InfraMgr",

"opName": "vacs:userAPIGetContainerDetails"

}

userAPIGetTemplate

Method

GET

Resource URL

https:///app/api/rest?formatType=json&opName=vacs:userAPIGetTemplate&opData={param0:}

Description

Provides the VACS template details.

Sample URL

http://



21

\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig\"},\"srcRules\":

{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"attributeValue\":\"WebZone\",\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature

.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"AppZone\",\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateACL.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"name\":\"dropWebToDBRule\",\"firewallAction\":\"drop\",\"matchCriteria\":\"match-

all\",\"protocolServiceOption\":\"Protocol\",\"protocol\":true,\"services\":{\"list\":[],\"moTypeName

\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig\"},\"srcRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"attributeValue\":\"WebZone\",\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027 target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature

.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{\"list\":[{\"attributeTyp

e\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"DBZone\",\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateACL.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"name\":\"allowAppToDBRule\",\"fire

wallAction\":\"permit\",\"matchCriteria\":\"match-all\",\"protocolServiceOption\":\"Protocol\",\"protocol\":true,\"services\":{\"list\":[],\"moTypeName

\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig\"},\"srcRules\":

{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"AppZone\",\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{\"list\":[{\"attributeTyp

e\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"DBZone\",\"onlineHelp\":\"\\u003ca


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateACL.html\\u0027 target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"name\":\"dropDBToWebRule\",\"firew

allAction\":\"drop\",\"matchCriteria\":\"match-

all\",\"protocolServiceOption\":\"Protocol\",\"protocol\":true,\"services\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig\"},\"srcRules\":

{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"attributeValue\":\"DBZone\",\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"WebZone\",\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"name\":\"dropAppToWebRule\",\"firewallAction\":\"drop\",\"matchCriteria\":\"match-



Name\",\"attributeValue\":\"AppZone\",\"onlineHelp\":\"\\u003ca


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{\"list\":[{\"attributeTyp

e\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"WebZone\",\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateACL.html\\u0027



22

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"name\":\"permitAnyToWebRule\",\"fi

rewallAction\":\"permit\",\"matchCriteria\":\"match-

any\",\"protocolServiceOption\":\"Service\",\"protocol\":true,\"services\":{\"list\":[{\"protocalOperator\":\"eq\",\"protocalValue\":\"TCP\",\"serviceName\":\"http\",\"servicePort\":80,\"onlineHelp\":\"

\\u003ca href\\u003d\\u0027/app/ONLINEHELP/FirewallPolicyACLRule.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"protocalOperator\":\"eq\",\"protocalValue\":\"TCP\",\"serviceName\":\"http\",\"servicePort\":8080,\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"protocalOperator\":\"eq\",\"protocalValue\":\"TCP\",\"serviceName\":\"https\",\"servicePort\":443,\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"protocalOperator\":\"eq\",\"protocalValue\":\"TCP\",\"serviceName\":\"https\",\"servicePort\":8443,\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig\"},\"srcRules\":{\"list\":[],\"moTypeNam

e\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{

\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone Name\",\"attributeValue\":\"WebZone\",\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca


target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},{\"name\":\"permitWebToAnyRule\",\"firewallAction\":\"permit\",\"matchCriteria\":\"match-



Name\",\"attributeValue\":\"WebZone\",\"onlineHelp\":\"\\u003ca


.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"destRules\":{\"list\":[],\"moTypeName\

":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\"},\"onlineHelp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateACL.html\\u0027


.stingray.firewallpolicy.model.StgVNMCAclPolicies\"},\"vmNetworks\":{\"list\":[{\"networkName\":\"lan

0\",\"networkType\":1,\"vlanPool\":1,\"vxlanPool\":-

1,\"portGroup\":\"\",\"ipSubnetPool\":1,\"staticIPPool\":-1,\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateVMNetworks.html\\u0027 target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature

.stingray.template.ui.StgStingrayVMNetwork\",\"validatorName\":\"StgStingrayVMNetworkListValidator\"}

,\"vms\":{\"list\":[{\"zone\":\"WebZone\",\"appName\":\"web\",\"appDescription\":\"\",\"imageId\":\"VM-template-

1NIC\",\"numVCPUs\":1,\"memoryMB\":256,\"cpuReservationMHz\":0,\"memoryReservationMB\":0,\"diskSize\"

:0,\"passwordResetType\":1,\"templateRootLogin\":\"root\",\"templateRootPassword\":\"\",\"isUseImageNetwork\":false,\"networks\":{\"list\":[{\"appName\":\"vnic0\",\"networkName\":\"lan0\",\"adapterType\

":\"e1000\",\"enablePublicIPMapping\":false}],\"moTypeName\":\"com.cloupia.feature.stingray.template.

ui.StgStingrayVirtualMachineNetworkConfig\",\"validatorName\":\"StingrayVirtualMachineNetworkConfigListValidator\"},\"maxQuantity\":1,\"initialQuantity\":2,\"isStorageEfficiencyEnabled\":false,\"onlineH

elp\":\"\\u003ca href\\u003d\\u0027/app/ONLINEHELP/TemplateVirtualMachine.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}],\"moTypeName\":\"com.cloupia.feature.stingray.template.ui.StgStingrayVirtualMachineConfig\",\"validatorName\":\"StgStingrayVirtualMachine

ConfigListValidator\"},\"slbConfig\":{\"tierHAScale\":\"WebZone\",\"networkHAScale\":\"\",\"protocolH

AScale\":\"TCP\",\"persistenceHAScale\":\"None\",\"frontTCPPortHAScale\":80,\"backTCPPortHAScale\":80,\"frontTCPHttpsHAScale\":443,\"backTCPHttpsHAScale\":443,\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/CustomTemplateLoadBalance.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},\"deploymentOptions\":{\"deploymentOption\":\"Large\",\"vcenter\":\"VC-chao-9\",\"n1kDVSwitch\":\"VSM-24\",\"virtualComputePolicy\":\"VC-

chao-9 - Default Computing Policy\",\"virtualStoragePolicy\":\"VC-chao-9 - Default Storage

Policy\",\"virtualSystemPolicy\":\"sys1\",\"deployCSR\":true,\"deployVSG\":true,\"deploySLB\":true,\"ha\":\"No\",\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/TierTemplateDeployment.html\\u0027

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"},\"vpnConfig\":{},\"algConfig\":{\"http\":true,\"https\":true,\"ftp\":true,\"dns\":true,\"icmp\":true,\"sqlnet\":false,\"mssql\":false,\"ld

ap\":false,\"onlineHelp\":\"\\u003ca

href\\u003d\\u0027/app/ONLINEHELP/CustomAppLayerGateway.html\\u0027



23

target\\u003d\\u0027_blank\\u0027\\u003eHelp\\u003c/a\\u003e\"}}", "serviceError":null,

"serviceName":"InfraMgr", "opName":"vacs:userAPIGetTe

userAPIVACSCreateContainerRest

Method

PUT

Resource URL

https:///cloupia/api-v2/VACSCreateContainerRest

Description

Creates container using parameterized template payload. The template created during the container creation

process is not saved to the Cisco VACS UI and gets deleted once container creation is successful.

Template is created with the

You must modify the following mandatory parameters in the payload:

1. networkResourcePool List:

managementIpPool

csrUplinkIPPool

csrIPType

parameters]

2. vmNetworks List:

networkType [If network type is VLAN modify vlanPool parameter and If type is VXLAN, modify

vxlanPool]

vlanPool

vxlanPool

ipSubnetPool

staticIPPool

3. vms List:

imageId

4. deploymentOptions

deploymentOption

vcenter

n1kDVSwitch

virtualComputePolicy

virtualStoragePolicy

virtualSystemPolicy

deployCSR

deployVSG

deploySLB

Sample URL

https:///cloupia/api-v2/VACSCreateContainerRest

Accessible

Administrator/end user



24

Sample XML Payload

1. Custom Template in a HA mode

rest1

Default Group

{"svcTemplateName":"Custom template in HA Rest","templateDescription":null,"containerType":"Stingray - Custom

Container","containerTypeSummary":null,"templateDefinitionData":"{\"networkResourcePool\":{\"label_managementip

pool\":null,\"managementIpPool\":\"mgt\",\"label_extraspace\":null,\"label_csrnetconfig\":null,\"csrUplinkIPPool\":\"

uplink\",\"csrIPType\":\"Private\",\"csrL3RoutingProtocol\":\"EIGRP\",\"autonomousNumber\":\"\",\"mtu\":\"1500\"

,\"onlineHelp\":null},\"pnscZones\":{\"list\":[],\"moTypeName\":\"com.cloupia.lib.cIaaS.vnmc.model.VNMCZoneConfi

g\",\"validatorName\":null},\"pnscAcls\":{\"list\":[],\"moTypeName\":\"com.cloupia.lib.cIaaS.vnmc.model.VNMCAclPo

licies\",\"validatorName\":null},\"stgPnscZones\":{\"list\":[{\"zoneName\":\"Web\",\"zoneDesc\":\"\",\"vnmcZoneRu

les\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneRuleConfig\",\"vali

datorName\":null},\"onlineHelp\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMC

ZoneConfig\",\"validatorName\":null},\"onlineHelpSecurityZone\":null,\"stgPnscAcls\":{\"list\":[],\"moTypeName\":\"

com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCAclPolicies\",\"validatorName\":null},\"onlineHelpACLRules\

":null,\"vmNetworks\":{\"list\":[{\"networkName\":\"lan0\",\"networkType\":\"VLAN\",\"vlanPool\":\"vlanpolicy\",\"

vxlanPool\":\"\",\"portGroup\":\"\",\"ipSubnetPool\":\"Subnet1\",\"staticIPPool\":\"\",\"onlineHelp\":null}],\"moTyp

eName\":\"com.cloupia.feature.stingray.template.ui.StgStingrayVMNetwork\",\"validatorName\":\"StgStingrayVMNetw

orkListValidator\"},\"onlineHelpVMNetworks\":null,\"vms\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.

template.ui.StgStingrayVirtualMachineConfig\",\"validatorName\":\"StgStingrayVirtualMachineConfigListValidator\"},\"o

nlineHelpNewVM\":null,\"slbConfig\":{\"tierHAScale\":null,\"networkHAScale\":null,\"protocolHAScale\":null,\"persist

enceHAScale\":null,\"label_http\":null,\"frontTCPPortHAScale\":80,\"backTCPPortHAScale\":80,\"label_https\":null,\"

frontTCPHttpsHAScale\":443,\"backTCPHttpsHAScale\":443,\"onlineHelp\":null,\"Label_space\":null,\"label_note_for

_custom\":null,\"label_note_for_non_custom\":null,\"onlineTemplateHelp\":null,\"onlineContainerHelp\":null},\"deploy

mentOptions\":{\"deploymentOption\":\"Small\",\"vcenter\":\"Aditya-

vc\",\"n1kDVSwitch\":\"AdityaN1K\",\"virtualComputePolicy\":\"Aditya-vc - Default Computing

Policy\",\"virtualStoragePolicy\":\"Aditya-vc - Default Storage

Policy\",\"virtualSystemPolicy\":\"local\",\"endUserSelfServicePolicy\":\"\",\"deployCSR\":true,\"deployVSG\":false,\

"deploySLB\":false,\"ha\":\"No\",\"onlineHelp\":null,\"haModeLabel\":null},\"vpnConfig\":{\"enableSiteToSiteIPSecV

PN\":null,\"vpnPreSharedKey\":null,\"encryption\":null,\"hash\":null,\"remoteSiteIPAddress\":null},\"algConfig\":{\"htt

p\":true,\"https\":true,\"ftp\":true,\"dns\":true,\"icmp\":true,\"sqlnet\":false,\"mssql\":false,\"ldap\":false,\"onlineHe

lp\":null}}","onlineHelp":"N/A"}

]]>

2. Custom Template in a non-HA mode



25

rest2

Default Group

{"svcTemplateName":"Custom template in Non-HA Rest","templateDescription":null,"containerType":"Stingray -

Custom






licies\",\"validatorName\":null},\"stgPnscZones\":{\"list\":[{\"zoneName\":\"appzone\",\"zoneDesc\":\"\",\"vnmcZo

neRules\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneRuleConfig\",

\"validatorName\":null},\"onlineHelp\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgV

NMCZoneConfig\",\"validatorName\":null},\"onlineHelpSecurityZone\":null,\"stgPnscAcls\":{\"list\":[{\"policyName\":

null,\"policyDesc\":null,\"name\":\"acl1\",\"descr\":\"\",\"firewallAction\":\"permit\",\"matchCriteria\":\"match-

all\",\"protocolServiceOption\":\"Protocol\",\"protocol\":true,\"protocalOperator\":\"\",\"protocalValue\":\"\",\"servi

ces\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig

\",\"validatorName\":null},\"srcRules\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model

.StgVnmcAclPolicyRuleConfig\",\"validatorName\":null},\"destRules\":{\"list\":[],\"moTypeName\":\"com.cloupia.featu

re.stingray.firewallpolicy.model.StgVnmcAclPolicyRuleConfig\",\"validatorName\":null}}],\"moTypeName\":\"com.cloup

ia.feature.stingray.firewallpolicy.model.StgVNMCAclPolicies\",\"validatorName\":null},\"onlineHelpACLRules\":null,\"vm

Networks\":{\"list\":[{\"networkName\":\"lan0\",\"networkType\":\"VLAN\",\"vlanPool\":\"vlanpolicy\",\"vxlanPool\"

:\"\",\"portGroup\":\"\",\"ipSubnetPool\":\"Subnet1\",\"staticIPPool\":\"\",\"onlineHelp\":null}],\"moTypeName\":\"

com.cloupia.feature.stingray.template.ui.StgStingrayVMNetwork\",\"validatorName\":\"StgStingrayVMNetworkListValida

tor\"},\"onlineHelpVMNetworks\":null,\"vms\":{\"list\":[{\"templateName\":null,\"zone\":\"appzone\",\"appName\":\"

appvm\",\"appDescription\":\"\",\"vmImageType\":\"VM

Template\",\"imageId\":\"AppVM\",\"numVCPUs\":1,\"memoryMB\":256,\"cpuReservationMHz\":0,\"memoryReserv

ationMB\":0,\"diskSize\":0,\"passwordResetType\":1,\"templateRootLogin\":\"root\",\"templateRootPassword\":\"\",

\"appCategory\":null,\"isUseImageNetwork\":false,\"networks\":{\"list\":[{\"appName\":\"nic1\",\"networkName\":\"

lan0\",\"adapterType\":\"e1000\",\"ipAddress\":null,\"enablePublicIPMapping\":false}],\"moTypeName\":\"com.clou

pia.feature.stingray.template.ui.StgStingrayVirtualMachineNetworkConfig\",\"validatorName\":\"StingrayVirtualMachine

NetworkConfigListValidator\"},\"maxQuantity\":1,\"initialQuantity\":1,\"isStorageEfficiencyEnabled\":false,\"onlineHelp

\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.template.ui.StgStingrayVirtualMachineConfig\",\"validatorNam

e\":\"StgStingrayVirtualMachineConfigListValidator\"},\"onlineHelpNewVM\":null,\"slbConfig\":{\"tierHAScale\":null,\"

networkHAScale\":null,\"protocolHAScale\":null,\"persistenceHAScale\":null,\"label_http\":null,\"frontTCPPortHAScal

e\":80,\"backTCPPortHAScale\":80,\"label_https\":null,\"frontTCPHttpsHAScale\":443,\"backTCPHttpsHAScale\":443

,\"onlineHelp\":null,\"Label_space\":null,\"label_note_for_custom\":null,\"label_note_for_non_custom\":null,\"onlineT

emplateHelp\":null,\"onlineContainerHelp\":null},\"deploymentOptions\":{\"deploymentOption\":\"Large\",\"vcenter\":

\"Aditya-vc\",\"n1kDVSwitch\":\"AdityaN1K\",\"virtualComputePolicy\":\"Aditya-vc - Default Computing


Policy\",\"virtualSystemPolicy\":\"local\",\"endUserSelfServicePolicy\":\"\",\"deployCSR\":true,\"deployVSG\":true,\

"deploySLB\":false,\"ha\":\"No\",\"onlineHelp\":null,\"haModeLabel\":null},\"vpnConfig\":{\"enableSiteToSiteIPSecV




]]>

3. Blank Template



26

rest3

Default Group

{"svcTemplateName":"Empty Template Rest","templateDescription":null,"containerType":"Stingray - Custom



uplink\",\"csrIPType\":null,\"csrL3RoutingProtocol\":null,\"autonomousNumber\":null,\"mtu\":\"1500\",\"onlineHelp\"

:null},\"pnscZones\":{\"list\":[],\"moTypeName\":\"com.cloupia.lib.cIaaS.vnmc.model.VNMCZoneConfig\",\"validatorN

ame\":null},\"pnscAcls\":{\"list\":[],\"moTypeName\":\"com.cloupia.lib.cIaaS.vnmc.model.VNMCAclPolicies\",\"validat

orName\":null},\"stgPnscZones\":{\"list\":[{\"zoneName\":\"appzone\",\"zoneDesc\":\"\",\"vnmcZoneRules\":{\"list\

":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneRuleConfig\",\"validatorName\

":null},\"onlineHelp\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneConfig\

",\"validatorName\":null},\"onlineHelpSecurityZone\":null,\"stgPnscAcls\":{\"list\":[],\"moTypeName\":\"com.cloupia.

feature.stingray.firewallpolicy.model.StgVNMCAclPolicies\",\"validatorName\":null},\"onlineHelpACLRules\":null,\"vmN

etworks\":{\"list\":[{\"networkName\":\"lan0\",\"networkType\":\"VLAN\",\"vlanPool\":\"vlanpolicy\",\"vxlanPool\":\

"\",\"portGroup\":\"\",\"ipSubnetPool\":\"Subnet1\",\"staticIPPool\":\"\",\"onlineHelp\":null}],\"moTypeName\":\"c

om.cloupia.feature.stingray.template.ui.StgStingrayVMNetwork\",\"validatorName\":\"StgStingrayVMNetworkListValidat

or\"},\"onlineHelpVMNetworks\":null,\"vms\":{\"list\":[{\"templateName\":null,\"zone\":\"appzone\",\"appName\":\"

appvm\",\"appDescription\":\"\",\"vmImageType\":\"VM

Template\",\"imageId\":\"AppVM\",\"numVCPUs\":1,\"memoryMB\":256,\"cpuReservationMHz\":0,\"memoryReserv

ationMB\":0,\"diskSize\":0,\"passwordResetType\":1,\"templateRootLogin\":\"root\",\"templateRootPassword\":\"\",

\"appCategory\":null,\"isUseImageNetwork\":false,\"networks\":{\"list\":[{\"appName\":\"nic\",\"networkName\":\"l

an0\",\"adapterType\":\"e1000\",\"ipAddress\":null,\"enablePublicIPMapping\":false}],\"moTypeName\":\"com.clou

pia.feature.stingray.template.ui.StgStingrayVirtualMachineNetworkConfig\",\"validatorName\":\"StingrayVirtualMachine

NetworkConfigListValidator\"},\"maxQuantity\":1,\"initialQuantity\":1,\"isStorageEfficiencyEnabled\":false,\"onlineHelp

\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.template.ui.StgStingrayVirtualMachineConfig\",\"validatorNam

e\":\"StgStingrayVirtualMachineConfigListValidator\"},\"onlineHelpNewVM\":null,\"slbConfig\":{\"tierHAScale\":null,\"

networkHAScale\":null,\"protocolHAScale\":null,\"persistenceHAScale\":null,\"label_http\":null,\"frontTCPPortHAScal

e\":80,\"backTCPPortHAScale\":80,\"label_https\":null,\"frontTCPHttpsHAScale\":443,\"backTCPHttpsHAScale\":443

,\"onlineHelp\":null,\"Label_space\":null,\"label_note_for_custom\":null,\"label_note_for_non_custom\":null,\"onlineT

emplateHelp\":null,\"onlineContainerHelp\":null},\"deploymentOptions\":{\"deploymentOption\":\"Large\",\"vcenter\":

\"Aditya-vc\",\"n1kDVSwitch\":\"AdityaN1K\",\"virtualComputePolicy\":\"Aditya-vc - Default Computing


Policy\",\"virtualSystemPolicy\":\"local\",\"endUserSelfServicePolicy\":\"\",\"deployCSR\":false,\"deployVSG\":false,

\"deploySLB\":false,\"ha\":\"No\",\"onlineHelp\":null,\"haModeLabel\":null},\"vpnConfig\":{\"enableSiteToSiteIPSecV




]]>

4. Internal Template with SLB in HA



27

rest4

Default Group

{"svcTemplateName":"Internal Template with SLB in HA Rest","templateDescription":null,"containerType":"Stingray -

3 Tier

(Internal)","containerTypeSummary":null,"templateDefinitionData":"{\"networkResourcePool\":{\"label_managementip





licies\",\"validatorName\":null},\"stgPnscZones\":{\"list\":[{\"zoneName\":\"WebZone\",\"zoneDesc\":null,\"vnmcZo

neRules\":{\"list\":[{\"attributeType\":\"vm\",\"attributeName\":\"VM

Name\",\"operator\":\"contains\",\"attributeValue\":\"web\",\"prefixedIpAddressValue\":null,\"prefixedSubnetValue\

":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneRuleConfig\",\"validatorNa

me\":null},\"onlineHelp\":null},{\"zoneName\":\"AppZone\",\"zoneDesc\":null,\"vnmcZoneRules\":{\"list\":[{\"attribut

eType\":\"vm\",\"attributeName\":\"VM

Name\",\"operator\":\"contains\",\"attributeValue\":\"app\",\"prefixedIpAddressValue\":null,\"prefixedSubnetValue\"

:null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneRuleConfig\",\"validatorNam

e\":null},\"onlineHelp\":null},{\"zoneName\":\"DBZone\",\"zoneDesc\":null,\"vnmcZoneRules\":{\"list\":[{\"attributeTy

pe\":\"vm\",\"attributeName\":\"VM

Name\",\"operator\":\"contains\",\"attributeValue\":\"db\",\"prefixedIpAddressValue\":null,\"prefixedSubnetValue\":

null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneRuleConfig\",\"validatorNam

e\":null},\"onlineHelp\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVNMCZoneConfi

g\",\"validatorName\":null},\"onlineHelpSecurityZone\":null,\"stgPnscAcls\":{\"list\":[{\"policyName\":null,\"policyDes

c\":null,\"name\":\"allowWebToAppRule\",\"descr\":null,\"firewallAction\":\"permit\",\"matchCriteria\":\"match-

all\",\"protocolServiceOption\":\"Protocol\",\"protocol\":true,\"protocalOperator\":null,\"protocalValue\":null,\"servic

es\":{\"list\":[],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcACLPolicyServiceConfig\

",\"validatorName\":null},\"srcRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"operator\":null,\"attributeValue\":\"WebZone\",\"zoneAttributeValue\":null,\"prefixedIpAddressValue\":null,

\"prefixedSubnetValue\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicy

RuleConfig\",\"validatorName\":null},\"destRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"operator\":null,\"attributeValue\":\"AppZone\",\"zoneAttributeValue\":null,\"prefixedIpAddressValue\":null,\

"prefixedSubnetValue\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyR

uleConfig\",\"validatorName\":null}},{\"policyName\":null,\"policyDesc\":null,\"name\":\"dropWebToDBRule\",\"descr

\":null,\"firewallAction\":\"drop\",\"matchCriteria\":\"match-




Name\",\"operator\":null,\"attributeValue\":\"WebZone\",\"zoneAttributeValue\":null,\"prefixedIpAddressValue\":null,

\"prefixedSubnetValue\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicy

RuleConfig\",\"validatorName\":null},\"destRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"operator\":null,\"attributeValue\":\"DBZone\",\"zoneAttributeValue\":null,\"prefixedIpAddressValue\":null,\"

prefixedSubnetValue\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRul

eConfig\",\"validatorName\":null}},{\"policyName\":null,\"policyDesc\":null,\"name\":\"allowAppToDBRule\",\"descr\

":null,\"firewallAction\":\"permit\",\"matchCriteria\":\"match-




Name\",\"operator\":null,\"attributeValue\":\"AppZone\",\"zoneAttributeValue\":null,\"prefixedIpAddressValue\":null,\

"prefixedSubnetValue\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyR

uleConfig\",\"validatorName\":null},\"destRules\":{\"list\":[{\"attributeType\":\"zone\",\"attributeName\":\"Zone

Name\",\"operator\":null,\"attributeValue\":\"DBZone\",\"zoneAttributeValue\":null,\"prefixedIpAddressValue\":null,\"

prefixedSubnetValue\":null}],\"moTypeName\":\"com.cloupia.feature.stingray.firewallpolicy.model.StgVnmcAclPolicyRul



28

eConfig\",\"validatorName\":null}},{\"policyName\":null,\"policyDesc\":null,\"name\":\"dropDBToWebRule\",\"descr\

":null,\"firewallAction\":\"drop\",\"matchCriteria\":\"match-



",\"validatorName\":null},\"srcRules

Documents

Cisco Virtual Application Cloud Segmentation Services REST ...€¦ · Cisco Systems, Inc. 1 Cisco Virtual Application Cloud Segmentation Services REST API Guide, Release 5.5STV3.1