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://{server_ip}:30603/crosswork/

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, but we use Postman in all the examples on this page. To get the most out of this introduction, we recommend that you try using Postman as your REST client.

Complete installation and configuration guide for Postman is outside the scope of this document. The following steps provide an overview of basic installation and configuration as required for use with Crosswork Network Controller.

  1. Download Postman from https://www.postman.com.
  2. Install and launch Postman.
  3. Disable SSL verification in Postman.
    1. Start Postman.
    2. In the top right corner of the screen, click the tools icon and select Settings.
    3. In the General tab, disable SSL certificate verification option.

Task 3: Get the Authentication Token

Crosswork uses a token-based authentication scheme to authenticate your API requests, so these steps also explain how to request an authorization ticket and token and then pass it with the API requests.

Crosswork assigns each API request a job ID. You can check the status for these job IDs to see if the task was successful or not. The job ID status values are:

0 JOB_INVALID
1 JOB_REJECTED
2 JOB_ACCEPTED
3 JOB_DB_UPDATED
4 JOB_NOTIFICATION_PUBLISHED
5 JOB_COMPLETED
6 JOB_FAILED
  1. Verify that Cisco Crosswork Network Controller is running by opening a browser window, navigating to the server IP address, and logging in. Once you have logged in, you can minimize the browser window.
  2. From your desktop, launch Postman.
  3. You need to get a ticket before you can get a token. Select the Get Ticket request, and then click Send. Then copy the reply to the clipboard by clicking the copy icon.
  4. Update the Postman Environment with the new ticket value: Click the eye icon in the top right corner of the window. Then double-click the pen icon in the Current Value field for the ticket variable.
  5. Place the cursor in the ticket > Current Value field, then right-click on the field and select Paste. This will paste the new ticket value into the ticket > Current Value field. Press Enter to apply the change and then click outside the edit pop-up to close it.
  6. Now that we have a ticket, we can request an authorization token. Select the Get Token command and click Send. Click the copy icon to copy the response to the clipboard.
  7. Update the Postman Environment with the new token value: Click the eye icon in the top right corner of the window. Then double-click the pen icon in the Current Value field for the token variable.
  8. Place the cursor in the token > Current Value field, right-click on the field and select Paste. This will paste the new token value into the token > Current Value field. Press Enter to apply the change and then click outside the edit pop-up to close it.
  9. Check the job progress: Select Get Job and click Send. Verify that the job is in state 5 (JOB_COMPLETED).

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.

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

  • Ensure that SSL certificate verification is disabled in Postman settings.

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