Software Developer's Guide for Cisco Secure Access Control System 5.4
Using the REST Web Services
Downloads: This chapterpdf (PDF - 180.0KB) The complete bookPDF (PDF - 3.4MB) | Feedback

Using the Configuration Web Services

Table Of Contents

Using the Configuration Web Services

Supported Configuration Objects

Identity Groups

Attribute Info

Group Associations

Device Info

Query Object




Request Structure

URL Path

HTTP Methods

Response Structure

HTTP Status Codes


Returned Objects


Schema File

Sample Code

Using the Configuration Web Services

This chapter describes the environment that you must set up to use the Configuration web service and explains how to use it.

The Configuration web services are implemented as REST interfaces over HTTPS. There is no HTTP support.

Configuring REST web services are available on all ACS servers in the deployment, but only the ACS primary instance provides the full service that supports read and write operations. Secondary ACS instances provide read only access to the configuration data.

The Monitoring and Report Viewer displays the messages and audit logs for all REST activities.

Enabling the REST Web Interface on ACS CLI

You must enable the web interface on ACS before you can use the REST web service. To enable the web interface on ACS, from the ACS CLI, enter:

acs config-web-interface rest enable

For more information on the acs config-web-interface command, refer to

Viewing the Status of the REST Web Interface from ACS CLI

To view the status of the web interface, from the ACS CLI, enter:

show acs-config-web-interface

For more information on the show acs-config-web-interface command, refer to

Applications that interact with the ACS configuration REST service may use any administrator account to authenticate to the REST service. Authorization for the used account should be set to allow all activities that are done by the REST client.

Supported Configuration Objects

The Rest PI in ACS provides services for configuring ACS, and it is organized for each configuration feature. In ACS 5.4, the following five subsets of the ACS configuration are supported:

Common configuration objects

Users configuration objects, Hosts configuration objects, and Identity group configuration objects.

Network Device configuration objects

Device Group configuration objects

Device Group Type configuration objects

Table 4-1 lists the supported configuration objects.

Table 4-1 Supported Configuration Objects 

Main Supported Classes


Attribute Info

Also known as dynamic attributes or AV pair. Attribute Info is composed within Protocol User.

ACS Version

Supports Get method only.

Service Location

Supports getall method only.

It allows you to find the ACS instance that serve as primary and the ACS instance that provide Monitoring and Troubleshooting Viewer.

Error Message

Supports getall method only.

It allows you to retrieve all ACS message codes and message texts that are used on the REST Interface.


Protocol User

Full CRUD (Create, Read, Update, and Delete) and query support.

Identity Group

Full CRUD and query support.

Query is used to retrieve subgroups of a specific node. The list of users for each group is fetched by querying on the users.

Internal Host

Full CRUD and query support.

Network Device

Network Device

Full CRUD and query support.

Device Group

Network Device Group

Full CRUD and query support.

Device Group Type

Network Device Group Type

Full CRUD and query support.

This section contains:

Identity Groups

Attribute Info

Group Associations

Device Info

Identity Groups

The Identity Group object is used to manipulate nodes on the Identity Group hierarchy. The group name defines the full path of the node within the hierarchy. When you add a new node, you should be aware that the name of the node (which includes the full path) specifies where in the hierarchy the node should be attached. For example:

All Groups:CDO:PMBU

All Groups:CDO

All Groups:CDO:PMBU:ACS-Dev

Note You must create the upper level hierarchy (parent node) and then create the leaf node.
For example: To create the hierarchy, All Groups:US:WDC; we must create All Groups:US and then go ahead creating the next level in hierarchy.

In order to retrieve the child of a certain group, you can set a filter as"start with All groups:CDO".

Attribute Info

The AttributeInfo structure is an array of pairs of attribute names and attribute values.

The attribute name refers to the user dictionary, where the definition of the attribute, such as value type, can be found. The value of the attribute must conform with the dictionary definition.

The following is an example of JAVA representation for a user that has two attributes:

User user = new User();
                user.setAttributeInfo(new AttributeInfo[]{
        		new AttributeInfo("Department","Dev"),
        		new AttributeInfo("Clock","10 Nov 2008 12:12:34")

Group Associations

The REST Interface schema shows the association of the user to the Identity group, as a group name property on the user object.

Here is an example of associating a user to an identity group:

User user = new User();
        user.setIdenityGroupName("IdentityGroup:All Groups:Foo");

Device Info

The following is an example of a Java representation for the configuration of a network device group and information that is related to creating a network device. It is also a good example of using a GroupInfo object to define device groups.

IPSubnetType ip1 = new IPSubnetType();
                ip1.setIpSubnetExclude(new IPSubnetExcludeType().setIpAddress("");
IPSubnetType ip2 = new IPSubnetType();
                ip1.setIpSubnetExclude(new IPSubnetExcludeType().setIpAddress("");
TACACSConnection tacacsCon = new TACACSConnection();
RADIUSConnection radiusCon = new RADIUSConnection();
Device device = new Device();
                device.setGroupInfo(new GroupInfo[]{new GroupInfo("All 
Locations:Chennai","Location"),new GroupInfo("All Device Types:Router","Device Type"});
                device.setSubnets(new IPSubnetType[]{ip1,ip2});

To create a single IP without mask or ranges, you need to just create the IPSubnetType and associate the subnet to that object, as shown in the above example.

Note It is mandatory to provide information about at least one group to which the network device is associated while updating a network device using the REST interface. The network device may be associated with more than one group. The group information that is not provided will automatically be updated with a default value.

Query Object

The REST Interface schema exposes a query object to define criteria and other query parameters. The query object is used for Users, Identity Groups, Network Device, Network Device Groups, and Internal Hosts.

The query object includes parameters that apply to:





You can use the query object to retrieve a filtered result set. You can filter users or identity groups, based on the following criteria:

Simple condition—Includes property name, operation, and value. For example, name STARTS_WITH "A".

The following operations are supported for filtering:









And condition— Includes set of simple conditions. All simple condition must be evaluated to be True in order for the and condition to be matched.

Here is an XML-based example for the "And" filter.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <ns2:query xmlns:ns2="">

Note The XML tag numberOfItemsInPage has been changed to numberofItemsInPage (from upper case "O" to lower case "o") in patch 3. You need to install patch 3 to get this change reflected in ACS.


Here is a Java-based example for the "And" filter:

                  Query query = new Query();
                  SimpleFilter simpleFilter = new SimpleFilter();
                  SimpleFilter simpleFilter1 = new SimpleFilter();
                  AndFilter andFilter = new AndFilter();
                  andFilter.setSimpleFilters(new SimpleFilter[] { simpleFilter,
                              simpleFilter1 });


You can use the query object to sort the results. You can sort based on the following criteria:

One property to sort by

Direction of sorting (Ascending/Descending)


You can set the query object with the following paging parameters:

Page number, which is the requested page

Number of objects in a page

Paging is stateless. That is, the required page is calculated from scratch for every request. This means that paging could skip objects or return them twice, in case objects were added or deleted concurrently.

Request Structure

ACS REST request is composed of:


HTTP method

Content—Includes ACS objects if applicable to the requested method. The ACS objects are represented in XML.

URL Path

URL includes:

Service name: Rest

Package name: Identity, Common, or Network Device

Object Type: User, Identity Group, and so on

Object Identifiers are valid with the GET and DELETE methods.

Operation name is required for operations other than CRUD, such as query.

Table 4-2 lists the URLs for each object.

Object Identifiers

Objects are identified by name or by object ID. The basic object key is the object name. You can also use the Object ID for the GET and DELETE methods. For POST and PUT, the method gets the object itself, which includes the identifiers.

You can specify the identifier on the URL in the following ways:

Name as the key: Rest/{package}/{ObjectType}/name/{name}

Object ID as the key: Rest//{package}/{ObjectType}/id/{id}

For a single instance per object type, no key is required. For example: REST/Common/ACSVersion

Table 4-2 URL Summary Table 


ACS Version


Single object exists

Service Location


Error Message




For some methods, there is additional data on the URL. See Table 4-3

Identity Group


For some methods, there is additional data on the URL. See Table 4-3

Network Device


For some methods, there is additional data on the URL. See Table 4-3

Device Group


For some methods, there is additional data on the URL. See Table 4-3

Internal Host


For some methods, there is additional data on the URL. See Table 4-3

HTTP Methods

HTTP methods are mapped to configuration operations (CRUD - Create, Read, Update, and Delete).

The common intrinsic methods are not specified within the URL, and are determined by the HTTP request method. In other cases, you need to add the configuration operation into the URL. HTTP methods are mapped to ACS operations:

HTTP GET—View an object or multiple objects.

HTTP POST—Create a new object.

HTTP DELETE—Delete a object.

HTTP PUT—Update an existing object. PUT is also used to invoke extrinsic methods (other than CRUD).

When the HTTP PUT method is used for operations other than CRUD, the URL specifies the required operation. This is also used to distinguish the message from the PUT method for update. The keyword "op" is included in the URL as follows:


For example, /Rest/Identity/IdentityGroup/op/query

Table 4-3 describes the primary ACS REST methods and their mapping to HTTP messages.

Table 4-3 HTTP Method Summary 

HTTP Method
Request content
Response on Success





Collection of Objects





An Object





An Object





Note For create, the Object ID property should not be set.

Rest Response Result, which includes Object ID.





Rest Result



/{ObjectType}/ id/{id}


Rest Result





Rest Result





List of Objects

1 Names in the URL are full names. ACS REST services does not support wildcards or regular expressions.

2 Update method replaces the entire object with the object provided in the request body, with the exception of sensitive properties.

Note The GET and DELETE methods using MAC addresses are applicable only for the Host object types. For example, /Host/macaddress/{macaddress}. The name attribute in these methods is replaced with MAC addresses. This is because of the Host object, which does not have the name attribute.

Note For the responses on failure, see ACS REST Result.

Response Structure

The response to REST request is a standard HTTP response that includes the HTTP status code and other data that is returned by web servers. In addition, the response can include the ACS REST result object or ACS configuration objects according to the type of request.

You should check the HTTP status code to find out the type of objects that are expected in the response body.

For 4xx HTTPS status codes except for 401 and 404, REST result object is returned.

For 5xx status codes other than 500, the message content includes text that describe the server error.

For 500 HTTP status codes, REST result is returned.

For 200 and 201 HTTP status codes, objects per the specific method or object type are returned.

For 204 HTTP status codes, no object is returned.

HTTP Status Codes

ACS returns the following types of status codes:

2xx for success

4xx for client errors

5xx for server errors

ACS does not return the following types of status codes:



The HTTP status code is returned within the HTTP response headers as well as within the REST result object.

Table 4-4 lists the HTTP status codes that are returned by ACS.

Table 4-4 Usage of HTTP Status Codes 

Status Code
Usage in ACS



Successful Get, create and query


OK with no content

Successful delete and update

No data is returned in the response body.


Bad Request

Request errors: Object validation failure, XML syntax error, and other error in request message

The request contains bad syntax or cannot be executed.

For example, if you try to create an object with a name that already exists, the object validation fails.

Detailed reasons can be found in the REST result object.



Authentication Failure/ Time outs

Similar to 403 error, but specifically for use when authentication failed or credentials are not available.



ACS is a secondary and cannot fulfill the request, or operation is not allowed per administrator authorization.

The request was valid, but the server refuses to respond to it.

Unlike a 401 error, authenticating will make no difference. Also, this error is displayed when an non-read request was sent to a secondary instance.


Not Found

For cases where the URL is wrong or the REST service is not enabled



A resource is no longer available.

A request was made for an object that does not exist. For example, deleting an object that does not exist.


Internal Server Error

For any server error that has no specific HTTP code.


The HTTP response for a REST request includes either requested objects or a REST result object. See Table 4-3 for details. ACS result includes:

HTTP status code

HTTP status text

ACS message code

ACS message

Object ID for successful CREATE method

Returned Objects

ACS returns objects for GET method and for query operation. The type of returned object is determined by the request URL.

When a GET method returns multiple objects, these are included in the response. If the returned list is too long, you should use filtering or paging options.


The WADL files contain the object structure (schema) and the methods for every object.

The WADL files are mainly documentation aids. You cannot generate client applications using WADL files.

The WADL file structure is according to W3C specification. For more information, see

To download the WADL files:

Step 1 From the ACS user interface, go to System Administration > Downloads > Rest Service

Step 2 Under ACS Rest Service WADL files, click Common or Identity and save the files to your local drive.

Schema File

ACS is shipped with four XSD files that describe the structure of the objects that are supported on ACS 5.4 REST interfaces.

The four XSD files are:

Common.xsd, which describes the following objects:



Error Message

ResultResult, RestCreateResult


Service Location



Identity.xsd, which describes the following objects:




Query.xsd, which describes the structure of query objects.

NetworkDevice.xsd, which describes the following objects:

Network Devices

Network Device Groups

Network Device Group Types

You can download the schema files in the same way as you download the WADL files. You can use the schema with available tools such as JAXB to generate schema classes.

You can develop HTTP client or use any third-party HTTP client code and integrate it with the schema classes that are generated from the XSD files.

Note It is highly recommended to generate REST client classes from the XSD files rather than coding XML or creating it manually.

Sample Code

ACS provides sample code for client application to help you develop an application that interacts with ACS REST Interface. The sample code can be downloaded in the same way as WADL and schema files.

The sample code is based on Apache HTTP Client and JAVA code generated by JAXB (xjc command) with the help of the XSD files. It includes sample codes for:

Get ACS Version

Get all users

Get All Service Locations

Get Filtered list of Users

Get list of Error messages

Get User by ID and by name

Create, Delete, Update user

Create, Delete, and Update identity group

Get IdentityGroup by name or ID

Get sub-tree of IdentityGroups

Get all Users of an Identity Group

Create, Delete, Update Network Device

Get Network Devices by ID and by name

Get All Network Devices

Query for Network Device

Create, Delete, Update Network Device Group

Get Network Device Group by ID or by name

Get sub-tree of Network Device Group

Query for Network Device Group

Create, Delete, Update Network Device Group Type

Get Network Device Group Type by ID and by name

Get All Network Device Group Type

Query for Network Device Group Type

Create, Delete, Update Internal Host

Get Internal Host by ID or Name

Get All Internal Host

Query for Internal Host