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.

Standard REST methods are supported on the API, which include POST, GET, and DELETE operations through HTTPS. The POST and DELETE methods are idempotent, meaning that there is no additional effect if they are called more than once with the same input parameters. The GET method is nullipotent, meaning that it can be called zero or more times without making any changes (or that it is a read-only operation). All payloads to and from the REST interface must 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 begins with the following base URL: https://{cnc_host}:{cnc_port}/crosswork/ where {cnc_host} is CNC management address which is the host name or the IP address (or virtual IP address), {cnc_port} is the port (e.g. 30603) that CNC listens on to receive API requests and return response.

Depending on the specific service, the full URL may contain an additional prefix relative to the base URL and the endpoint listed in the API reference.

Authorization Using User Credentials and API Token

Before you can send any requests to perform specific operations on the Crosswork Network Controller, you must login by POSTing a request containing a username and password for a user already configured in Crosswork Network Controller to obtain an authorization token that you can use in 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 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.

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 action is specified next to the API call in the API reference: API Action

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