Getting Started

The following sections introduce you to the standard Crosswork Network Automation REST API operations, and describe how to compose and test simple API calls to get you started.

The API supports standard REST methods, including POST, GET, and DELETE via HTTPS. Because POST and DELETE are idempotent, calling them multiple times with the same input parameters has no additional effect. The GET method is nullipotent; it performs Read-only operations and does not change the system, regardless of how often you call it. The REST interface requires all payloads to be in JSON format.

A typical REST API operation consists of three elements:

Request URL — The address of the resource to which you make the API call.

Request message — The JSON-formatted payload that contains the new data you want to add or update. For Read-only operation (GET) the request message is empty.

Request response — The JSON-formatted response that contains the requested information.

Base URL

Every API request starts with the base URL:

https://{cnc_host}:{cnc_port}/crosswork/

where {cnc_host} is the CNC management address (host name or IP/virtual IP), and {cnc_port} is the port (for example, 30603) CNC uses for API requests.

For example: https://198.51.100.1:30603

Depending on the service, the full URL may include an additional prefix before the base URL and the endpoint specified in the API reference.

Authorization Using User Credentials and API Token

To perform operations on the Crosswork Network Controller, you must first log in. Send a POST request with your configured username and password to receive an authorization token. Use this token for all subsequent API calls. For more information on configuring and managing user roles, refer to the Cisco Crosswork Network Controller Administration Guide for the version you downloaded.

To get started with the APIs, perform the following tasks:

  1. Download and install Cisco Crosswork Network Controller.
  2. Install a REST client and configure it to work with your local installation of the product.
  3. Get an authentication token to use in your REST client to run the Cisco Crosswork Network Automation API calls.

Task 1: Install Cisco Crosswork Network Controller

You can download the latest version of the Cisco Crosswork Network Controller from the "Download & Upgrade" section of Cisco Software Central.

To install the product, follow the instructions in the Cisco Crosswork Network Controller Installation Guide for the version that you downloaded.

Task 2: Install and Configure the REST Client

There are many REST clients available. You are welcome to use any client you like with Cisco Crosswork Network Automation APIs.

Task 3: Get the Authentication Token

Crosswork uses a JWT-based authentication scheme to authenticate the API requests. Use only the authentication token for the subsequent calls. Optionally, you can extract the token into a shell variable to simplify future calls. The default duration that a token is valid is 8 hours. For more information, refer to Authentication.

Use Case Examples

For details on NB API usage through user scenarios and examples for integrating external systems with CNC, refer to Guides.

API Resources Overview

This section provides a categorized overview of the available API resources, enabling developers to quickly identify and access the key functionalities that are offered by the Crosswork Network Controller.

  • Crosswork Infrastructure: This resilient, scalable platform hosts all Cisco Crosswork components. The infrastructure is based on a cluster architecture to ensure extensibility, scalability, and high availability.
  • Crosswork Data Gateway: A secure, common collection platform for gathering network data from multi-vendor devices that supports multiple data collection protocols, including MDT, SNMP, CLI, standards-based gNMI (dial-in), and syslog.
  • Crosswork Active Topology: Delivers comprehensive insights into network topology, traffic paths, and underlay transport policies, facilitating management and optimization of complex service deployments. Supports real-time analysis and proactive adjustments to ensure alignment with intent-based network objectives, while supporting network slicing at the OSI transport layer to optimize service management and meet intent-based requirements.
  • Crosswork Element Management Functions: Provides essential element management functions including Zero Touch Device onboarding, detailed inventory visualization, device fault and metrics monitoring, software image management and device configuration management.
  • Crosswork Service Health: Overlays a service-level view of the environment and allows operators to monitor the health of services (for example, L2/L3 VPN) based on rules established by the operator.
  • Crosswork Optimization Engine: Provides closed-loop tracking of the network state and real-time network optimization in response to changes in the network state, allowing operators to effectively maximize network capacity utilization and increase service velocity.
  • Crosswork Change Automation: Automates the process of deploying changes to the network.
  • Crosswork Health Insights: Performs real-time Key Performance Indicator (KPI) monitoring, alerting, and troubleshooting. It builds dynamic detection and analytics modules, allowing operators to monitor and alert network events based on user-defined logic.
  • Crosswork Workflow Manager Solutions: This platform streamlines device upgrades and management. It provides simplified field customizations and includes out-of-the-box support for Fleet Upgrade and Golden Config. You can also model and execute device migration MOPs or build ad-hoc applications.

Quick Start: Your First API Calls

Follow these three steps to authenticate and make your first API call to the Crosswork Network Controller.

Step 1: Obtain a Ticket Granting Ticket (TGT)

The first step in the authentication process is to exchange your user credentials for a TGT.

curl -k -s -X POST
https://{cnc_host}:30603/crosswork/sso/v1/tickets
-H 'Content-Type: application/x-www-form-urlencoded'
-H 'Accept: text/plain'
-d 'username={username}&password={password}

Response

The response is a plain-text string representing your TGT:

TGT-11-O-qlHH4Orn7bwmIQ5fx3Ys6Hrx8Q-cJzQsLqx...

Step 2: Exchange TGT for a JSON Web Token (JWT)

Use the TGT obtained in Step 1 to request a JWT (Bearer token). Include this token in all subsequent API requests to authorize them.

curl -k -s -X POST
https://{cnc_host}:30603/crosswork/sso/v2/tickets/jwt
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'tgt={TGT_FROM_STEP_1}&service=https://{cnc_host}/app-dashboard'

Response

eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCIsImetp...

Step 3: Make Your First API Call

Now that you have a JWT, use it in the Authorization header to make a functional API call. In this example, we retrieve a list of devices managed by the controller.

curl -k -X GET \
  https://{cnc_host}:30603/crosswork/inventory/v1/nodes \
  -H "Authorization: Bearer {JWT_FROM_STEP_2}" \
  -H "Accept: application/json"

Troubleshooting

A successful API call returns the 200 status code. If the response payload contains a status code other than 200, it typically also includes an error message to indicate a specific issue. In addition to the error message, you can check the following:

  • Check that you selected the correct action (for example, POST) for the specific API you are using.

  • The API reference lists the action next to each API call.

  • Check the health of Crosswork Network Controller using the GUI to verify there are no issues that could prevent you from using the APIs.