Sunday, January 3, 2021

Postman to interact with the Cisco SD-WAN REST API

 

Introduction

In this Learning Lab you will interact with the Cisco SD-WAN REST API from a third-party perspective, using Postman. Postman is a popular REST API client that you can download from their website.

In Introduction to Cisco SD-WAN REST APIs, you looked at the Swagger API documentation and you tried some API calls on the vManage instance itself. In this Learning Lab, you will start with authentication and then you will use a GET call to obtain information about the devices that are part of the DevNet SD-WAN sandbox fabric.

Objectives

When you have completed this Learning Lab, you will be able to:

  • Understand how to interact with the Cisco SD-WAN REST API.
  • Use the Code option in Postman to generate Python code, which will be used to automate configuration and management tasks.

Prerequisites

To complete this lab you need:

Step 1: Postman configuration

Before running any exercise using the Cisco SD-WAN 19.2 Reservable Sandbox, verify that your Postman configuration has SSL certificate verification disabled. The exercises will not work if the setting is enabled.

Import the Postman environment and collection into your client

After you clone the GitHub repository and install Postman, you will import two files that contain the values for the environment and collection into Postman. This will enable you to start interacting with the Cisco SD-WAN REST API.

A Postman environment is a list of variables that can be used to easily switch between different environments. By simply modifying the vManage username, password, port and hostname in the case of your environment, you can access and interact with different Cisco SD-WAN fabrics. The variables defined in the environment can be re-used also throughout the API calls that are defined in the collection.

A Postman collection is a group of API calls that define endpoints or resources that are available for that specific API. The collection also includes other parameters, headers or authentication methods that are needed to successfully complete the call.

  1. Open Postman and in the left upper corner click Import. A new window will pop up that gives us the option of browsing and choosing the two files.

  2. Click on Choose Files and to the location of the Postman folder that you cloned from GitHub and select Cisco-Reservable-SD-WAN-Env.postman_environment.json and Cisco-Reservable-SD-WAN.postman_collection.json.

  3. After you successfully import the files, make sure in the upper right corner of the application you select the Cisco SD-WAN Environment. Under Collections, ensure that the Cisco-SD-WAN collection is available.


Step 2: Authentication

The first step in interacting with an API is usually authentication. Authentication ensures that only legitimate users have access to the API. We can further limit the access by taking advantage of RBAC features, which enable you to assign users to specific groups with limited permissions, such Administrator or Operator.

This section provides an overview of authentication. For more detailed information about how the Cisco SD-WAN REST API is structured, how to authenticate, and the endpoints and resources that are accessible over the API, you can refer to the Swagger-based documentation in vManage and the REST API documentation.

Creating an authentication call

In your Cisco-SD-WAN collection, you can see that the first API call that you have is called Authentication and is in a folder named Authentication.

  • The Authentication call is a POST call.
  • To define the endpoint for the authentication call, you use the environment variable {{vmanage}}. These values will be replaced with the ones you have defined in the environment sandboxsdwan.cisco.com and 8443.
  • The resource that you are sending the API call to is j_security_check.

After the variables are replaced, the resulting endpoint for authentication is https://{ip_address}.com/j_security_check

Under the Headers tab, you define the Content-Type header.

  • For Cisco SD-WAN authentication, the type is application/x-www-form-urlencoded.
  • The username and password are URL-encoded in the Body or the request and are sent as key value pairs j_username and j_password. You will populate the values for the username and password from the environment variables with the same names.

These are all the parameters you need to authenticate to the vManage instance: the endpoint, the method, the header and the the body. When you click Send, the results should be similar to the following:

The body of the returned information should be empty and the status should be 200 OK if everything went well and the user was successfully authenticated. Notice that a Cookie named JSESSIONID was returned. This cookie will be used in the subsequent API calls that you will make in the next sections of this lab. This cookie has a limited lifetime and is a temporary representation of the successful authentication of the devnetuser account.

API Cross-Site Request Forgery Prevention

This feature adds protection against Cross-Site Request Forgery (CSRF) that could occur when using Cisco SD-WAN REST APIs. This protection is provided by including a CSRF token with API requests.

Step 3: GET SD-WAN fabric devices and their status

After you successfully authenticated and obtained the JSESSIONID cookie, you can now obtain the data that you want from the Cisco SD-WAN REST API. In the Postman collection that you imported, there is a folder named SD-WAN Fabric Devices that has several API calls.

This section reviews some of the available API calls. In the next sections you will see how you can use Postman to generate code that you can re-use in automation and network programmability scripts. Later, other Learning Labs will demonstrate how to use these code snippets to build your first Python application that takes full advantage of the SD-WAN REST API.

Fabric Devices

The Fabric Devices API call uses the GET method and the /dataservice/device endpoint to obtain a JSON-formatted list of all the devices that are part of the SD-WAN fabric. The output of this call is the same one you got inIntroduction to Cisco SD-WAN REST APIs, but in this case you used Postman to obtain the fabric information.

After you press Send in Postman for this first API call you should see a response similar to the following:

If you do not get a response like the one above, check to make sure that the status code response is 200 OK, if not the most probable cause is that your JSESSIONID cookie has expired and you need to re-authenticate once more. The output in the body of the response is verbose and very informative, containing extensive data about each device in the fabric.


Click HERE to expand and show expected /dataservice/device endpoint output

Devices Status

The next API in the collection is called Devices Status and uses the GET method on the /dataservice/device/monitor endpoint to obtain specific information regarding the status of all the devices in the fabric. The output of this API call should be also familiar if you've already completed the first lab in this module.

You can see below that the JSON output is the same and consistent no matter if you get the data through the swagger documentation or Postman.


Click HERE to expand and show expected /dataservice/device/monitor endpoint output

You have now seen how to interact with the Cisco SD-WAN REST API using Postman to get a list of devices in the fabric and their status. In the next sections, you will get additional information from the API about device counters and interface statistics.

Step 4: Device counters and interface statistics

You will now explore the API in more detail.

You may want to obtain information regarding the control plane connections of the fabric, the OMP peers statistics, BFD sessions status. You also want to know how many times have the devices been rebooted. If you search the documentation, you will find the API resource that will return the information that you are interested in: /dataservice/device/monitor.

The next API call in the Postman collection uses a GET method on the https://{{vmanage}}:{{port}}/dataservice/device/counters resource. Once you press Send and the request gets sent to the REST API, the response you receive back should look similar to the following

The JSON output in the body of the response should be similar to the following:


Click HERE to expand and show expected /dataservice/device/counters endpoint output

Next let's try to obtain interface statistics for the devices that are part of the SD-WAN fabric. The endpoint that will return extensive statistics for all the interfaces on all the devices in the fabric is /dataservice/statistics/interface. In the fourth API call in the Postman collection you are exploring this GET call in more detail. Just like the other GET calls so far, the JSESSIONID cookie is being used for authentication purposes and once you press Send in Postman, the output should be similar to the one below.

Depending on the size of the fabric, this call can take a large amount of time to return data or time out entirely. For the DevNet Sandbox SD-WAN fabric, which is a very small installation, it took almost 4 seconds for the response to be processed and delivered and it contains more than 100,000 lines of key-value pairs. I've included part of the JSON output for this call below for your reference. You can clearly see the power of the API, in which, with one call you can obtain extensive statistics for all the interfaces on all the devices in the fabric. By passing different parameters with this API call, like specific time intervals, specific devices or even specific interfaces, the output can be limited significantly.

Note: The output that you will receive may be thousands of lines long. The sample here has been truncated for display purposes.


Click to expand /dataservice/statistics/interface endpoint output

In the next section of this Learning Lab. you will learn how you can use Postman to generate Python code. You will use this code in other Learning Labs to build applications using all the information exposed by the SD-WAN REST API.

Step 5: Generate code with Postman

You've learned how to authenticate to the Cisco SD-WAN REST API and how to interact with it to extract data by using Postman. Postman has another very useful feature: code generation.

Once you build your API call, you specify the method, the endpoint, the headers, body, authentication and parameters, and then you can generate code in several programming languages that will re-create the same API call in the programming language you've chosen.

The following example uses the Authentication call from the collection. On the right hand side of the Postman client there's a Code option:

If you click on the Code option, you can select between several programming languages, including Python, Ruby, Go, C#, C, NodeJS, JavaScript, and PHP. If you select Python, the Authentication will be reproduced in Python by using the requests library. The following image shows the Python code generated by Postman. Use Copy to clipboard to copy the code snippet in the Postman interface, after which you can paste the code in your favorite IDE and start to use it.

At the top of the code snippet, the requests library is imported, after which variables are defined for the API resource that is being accessed (url), the username and password (payload), and the headers (headers).

The response variable contains the response of the POST request and at the end, the text method of the response object is displayed to the user.

You can do the same for all the other calls you explored in this Learning Lab and obtain the Python code for them. You can then combine them in scripts and applications for automation and network programmability purposes.

In the next Learning Lab, you will use Python to interact with the REST API and you will write your first script that will obtain data, parse it, extract information that you need, and process that information.


Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)