Chapter 1. Cisco DCNM REST APIs

- Getting Started

- Viewing REST APIs in DCNM

- Viewing REST APIs on DevNet

- Using GET APIs

- REST API Tool

Getting Started

Cisco DCNM provides REST APIs that allow third parties to test and develop application software. The REST API documentation is packaged with Cisco DCNM, and you can access it through any browser.

Accessing the DCNM REST API documentation involves the following steps:

1. Log in to your Cisco DCNM Web Client.

2. Go to the URL: https://DCNM-IP/api-docs.

3. Choose the definition from the Select a definition drop-down list.

The valid options are:

- DCNM

- Endpoint Locator

The default option is DCNM.

Note

The Endpoint Locator option appears only in the LAN Fabric deployments.

The following figure shows an example DCNM REST API documentation.

Example Cisco DCNM REST API Documentation

The REST API documentation packaged with the Cisco DCNM is limited to the following API categories:

API Categories

LAN Fabric

Media Controller

SAN Management

Alarms

Yes

Yes

Yes

Cloud Extension

Yes

–

–

Control - DCNM Tracker

Yes

–

–

Control - Fabrics

Yes

–

–

Control - Interface Service

Yes

–

–

Control - Inventory

Yes

–

–

Control - Links

Yes

–

–

Control - Policies

Yes

–

–

Control - Switches

Yes

–

–

Customization

Yes

Yes

Yes

DCNM Connect

–

–

Yes

DCNM Discovery

–

–

Yes

DCNM EPLD Image Management

Yes

–

–

DCNM Image Policy Management

Yes

–

–

DCNM Inventory

Yes

Yes

Yes

DCNM Package Management

Yes

–

Yes

DCNM Performance

–

–

Yes

DCNM PMN Discovered Hosts

–

Yes

–

DCNM PMN Events Management

–

Yes

–

DCNM PMN Flow Alias Management

–

Yes

–

DCNM PMN Flow Policy Management

–

Yes

–

DCNM PMN Flow Status

–

Yes

–

DCNM PMN Global Settings

–

Yes

–

DCNM PMN Host Alias Management

–

Yes

–

DCNM PMN Host Policy Management

–

Yes

–

DCNM PMN RTP Service

–

Yes

–

DCNM PMN Static Receiver Management

–

Yes

–

DCNM PMN Topology Management

–

Yes

–

DCNM PTP Management

–

Yes

–

DCNM Session management

Yes

Yes

Yes

DCNM Storage

–

–

Yes

DCNM Templates

Yes

Yes

Yes

Image Management

Yes

Yes

Yes

Local Zones

–

–

Yes

Progress Tracker

Yes

–

–

Resource Manager operations

Yes

–

–

Service Network Operations

Yes

–

–

Telemetry

Yes

–

–

Top Down LAN Network Operations

Yes

–

–

Top Down LAN VRF Operations

Yes

–

–

Viewing REST APIs in DCNM

Launch https://DCNM-IP/api-docs.

Click Show/Hide corresponding to the API category. Alternatively, click on any category link to expand or collapse it. When you expand the category, you can see the corresponding APIs under it. The following figure shows the APIs in the DCNM Inventory category.

APIs in the DCNM Inventory Category

There are four types of API methods:

- GET: Fetch existing information or data from the DCNM server.

- POST: Create new information or data.

- DELETE: Delete existing information or data.

- PUT: Update existing information or data.

Viewing REST APIs on DevNet

You can view all the REST APIs listed in the DCNM on DevNet as well. For more information, see https://developer.cisco.com/docs/data-center-network-manager/.

Using GET APIs

To use a GET API in Cisco DCNM Web UI, perform the following steps:

Procedure

Step 1

Click the GET API you want to try out.

The API section expands and you can view the details of the API.

Step 2

Click Try it out.

Step 3

Enter the values under the Parameters area.

Step 4

Click Execute.

You can view the response body and response headers under the Responses area.

Step 5

(Optional) Click Download to download the response body.

Step 6

(Optional) Click Clear to clear the responses.

Note

The images are used to illustrate an example. The procedure remains the same for all GET APIs.

REST API Tool

Operations like discovery, fabric management, monitoring, and so on, which are performed in Cisco DCNM Web UI, invoke HTTP calls to fetch and commit the information accessed. The REST API tool enables you to examine the API call by viewing the structure of an API call. This tool also provides a corresponding CURL request to help with building quick prototypes and testing APIs.

The REST API Tool dialog box has the following fields.

Fields and Description for the REST API Tool Dialog Box

Field

Description

Filter

Enter any keyword to search the log.

scroll to new items

Check this check box to scroll to the new entries when you navigate back to the REST API Tool dialog box after you perform an operation in the Web UI.

This check box is checked by default.

clear log

Click clear log to clear the log in the dialog box.

API-docs

Click API-docs to view the Cisco DCNM REST API documentation in the Web UI. Clicking this option takes you to the following URL: https://DCNM-IP/api-docs

All actions you perform in the Cisco DCNM Web UI appear in the API inspector tool. The following information appears in the APIs invoked for every operation:

- HTTP method

- URI

- Payload

- HTTP status code

- Time taken for the operation

Click the URI to expand or collapse each REST method. You can perform the following actions after expanding a REST method:

- Prettify output: Click this option to arrange the response code in a more presentable way, which otherwise appears in a single line. Scroll through the response to view it completely.

- Copy response: Click this option to copy the response code to your clipboard.

- Copy CURL request: Click this option to copy the CURL request to your clipboard.

curl -k -XGET --header 'Dcnm-Token: <DCNM_TOKEN>' --header 'Content-Type: application/x-www-form-urlencoded' https://<ip-address>/fm/fmrest/dcnm/rbacNavigation/?uname=admin

The REST API Tool dialog box updates every time the Cisco DCNM Web UI updates.

To use the API inspector from the Cisco DCNM Web UI, perform the following steps:

Procedure

Step 1

Click the Gear icon in the top pane.

Step 2

Choose REST API Tool from the drop-down list.

The REST API Tool dialog box appears and the log is empty before you perform any operation in the Cisco DCNM Web UI.

Step 3

Minimize the REST API Tool dialog box.

Note

You can also keep the dialog box open, but not close it.

Step 4

Perform an operation in the Cisco DCNM Web UI.

Note

You can perform any operation in the Cisco DCNM Web UI like viewing any options, adding, deleting, and so on.

Step 5

Navigate back to the REST API Tool dialog box.

The log is populated with the REST APIs fetched depending on the operations you performed.

Note

Closing the REST API Tool dialog box, instead of minimizing it before performing any operations, clears the log.

For a demo on some of the operations that can be performed using the REST API tool, see the Using REST API Tool in Cisco DCNM video.

Full Cisco Trademarks with Software License

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

All printed copies and duplicate soft copies of this document are considered uncontrolled. See the current online version for the latest version.

Cisco has more than 200 offices worldwide. Addresses and phone numbers are listed on the Cisco website at www.cisco.com/go/offices.

The documentation set for this product strives to use bias-free language. For purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on standards documentation, or language that is used by a referenced third-party product.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: https://www.cisco.com/c/en/us/about/legal/trademarks.html. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1721R)