Your Browser is Out of Date

ShareDemos uses technology that works best in other browsers.
For a full experience use one of the browsers below

Blogs

Short articles that discuss SD-WAN solutions

Blogs(1)

Tag :

All Tags

Author :

All Authors

VMware SD-WAN Edge

Using the VMware SD-WAN Orchestrator API to build custom reporting tools

Curtis Bunch

Mon, 05 Apr 2021 22:04:10 -0000

|

Read Time: 0 minutes

What are APIs?

In this blog post, I will lay out the fundamentals of why and how to use a RESTful API. This is a relatively new journey for me, and I want to share with you my eureka moments and hopefully inspire you in the way that you handle network device management. I believe there is nothing better than a working example, so I’ve included a working API application that shows the peak bandwidth used by all active edges in your enterprise.

Before we get into Postman and leveraging existing SD-WAN APIs, let us break down what an API is, what REST means, and how the two come together.

An API, or Application Programming Interface, is simply an intermediary software layer which allows two applications to communicate with each other. The Internet is largely built on this principle, and the VMware SD-WAN Orchestrator is no exception. For example, when you go to Monitor > Edges, a list of your edges appears.

This list of Edges appears because the UI is making an API request for you and the Orchestrator web server is responding back accordingly. An API call or request consists of an HTTP method, headers, and a request body. The request body contains a method. In the request above, the HTTP method is GET, one of the headers specifies the body type, and another specifies the authentication method.

You can see this process in action by using Chrome and the developer tool set. Press Ctrl+Shift+I to open the developer tools. Go to the Network tab and filter by XHR. Navigating the various portals and objects listed, you see multiple API methods being made as you navigate the screens. In this case, when you click Edges, the Orchestrator application is sending a well-known method named /enterprise/getEnterpriseEdgeList to the Orchestrator API host, and the web server is responding back with the appropriate data associated with that method.

Click the Preview tab and you will see all the data associated with the request, from creation date, edge name, serial numbers, and software revision.

Knowing this, you can browse the Orchestrator UI with the developer tools open and see exactly how information is sent and obtained. This is the cornerstone of building an application in Postman, or any modern programming language, to extract additional value from the Orchestrator API.

The terms API, REST, and RESTful are new to networking engineering, but as you have seen, you have been using RESTful systems daily as you browse the Internet. So, what is REST then? REST stands for REpresentation State Transfer, and it is the most common approach to designing and developing network applications. To be RESTful is to adhere to the REST design guidelines. This approach relies on a stateless client/server model, in which the client tracks the session and the server holds no client state or context. And best yet, HTTP is the most commonly used underlying transport protocol.

REST was originally designed as a paradigm for the HTTP protocol. As a result, most RESTful APIs are implemented over HTTP methods and use common verbs such as GET, PUT, and DELETE. A RESTful client connects to the interface, sends formatted data—for example, a configuration or show command—and the device responds with an HTTP code and optionally formatted data. The returned HTTP code is a standard response; for example, 200 = OK, 401 = unauthorized, and so on, informs the client if the command was successful. As shown below, to poll a single Edge interface, three requests must be made:

These requests can be written in any programming language that supports API requests. Later in this post, we will use Postman to make it easier to present, but you can use cURL or Client URL. cURL is part of the libcurl library and is part of any common Linux distribution. It provides a way to interact with URLs from the command-line interface. For example, using cURL, the second request above would look like this:

curl --location --request POST 'https://vco109-usca1.velocloud.net/portal/rest/enterprise/getEnterpriseEdges' \

--header 'Content-Type: application/json' \

--header 'Authorization: Token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlblV1aWQiOiI3ZWVjMTlkNC0zNzY0LTQ2MDctYWY1Mi00YjI0MWQ0Y2RiYjciLCJleHAiOjE2NDQ2MzE0NDgwMDAsInV1aWQiOiIyNWM0Y2M5MC0xNTNlLTExZTgtYTk0NC0wNjMyMzA4NzIwZjIiLCJpYXQiOjE2MTMwOTU0NTF9.oJeVnr1iuAqabf5XmcDOE2prieOp8rJriyrHfGLAKes' \

--data-raw '{

    "enterpriseId": 778,

    "with": [],

    "fieldsNeeded": [

        "id",

        "siteId",

        "modelNumber",

        "name"

    ]

}'

The method passes three key elements:

  1. The URL of the VCO and API method using HTTP POST
  2. A header specifying the authentication method used in a token
  3. A method body specifying the needed data to return (in this case, the Edge ID and SiteID information)

The returned response is structured data using JSON. For the previous example, the method would return a response body like this:

Status: 200 OK
Time: 73 ms
Size: 1.2 KB

Response Body:

[

    {

        "id": 17224,

        "siteId": 14117,

        "modelNumber": "edge3800",

        "name": "3400-Hub-HA",

        "isHub": true

    }

]

It is now up to your application to store the information in the response body to use in the next API request. The data is structured and enables extracting specific values in any language.

VMware SD-WAN Orchestrator API documentation

At the time of this post, two APIs exist for VMware SD-WAN, Orchestrator V1 and V2.  V2 is scheduled for release in mid-2022 and will be feature-compatible with V1. This blog post uses V1 and will be compatible with V2 with only minor changes. The following are links to both API versions:

Orchestrator API V1 responds to an API method using the VCO Portal. The VCO Portal allows network administrators to manage network and device configuration and to query current or historical network and device state. API clients may interact with the Portal through a REST interface using HTTP POST requests. The interface is accessible through the /portal/rest/ base path. This means that all API methods listed in the document are appended to this path. For example, using cURL again, the method /event/getEnterpriseEvents would look like this:

curl --header 'Content-Type: application/json' --data 

'{"enterpriseId":1}' --cookie cookies.txt -X POST 

https://vco.velocloud.net/portal/rest/event/getEnterpriseEvents

For this example, I use three methods. See the V1 documentation for explanations and more detail.

  • enterprise/getEnterprise – Gets data for the specified enterprise for your organization.
  • enterprise/getEnterpriseEdges – Gets all edges associated with the Enterprise ID.
  • metrics/getEdgeLinkSeries – Gets link metric time series data for an edge.

The first method, enterprise/getEnterprise, obtains the UID associated with the Orchestrator Enterprise account. The second fetches a list of edges and their associated details. The final method retrieves link metrics from the specific edges.

Before using any of these methods, let us discuss authentication. VMware SD-WAN Orchestrator API V1 supports both cookies and token authentication. Token-based authentication has gained prevalence over the last few years due to the rise of single-page applications, web APIs, and IoT. Another advantage of token-based authentication is that it is stateless. This means that the server does not keep a record, like cookies, of which users are logged in. Instead, a token is sent with every request and is specified in the header of the request.

I strongly recommend using token-based authentication and avoiding cookie-based authentication. Use of tokens is RESTful, and it is the only authentication method that Orchestrator V2 supports. Later in this post, I will show you how to obtain an API token from the Orchestrator UI and how to use the token for each method.

Using Postman for API testing

Postman is an API testing tool that simplifies API workflows and provides an ideal platform for getting started with building API requests. Recall that RESTful APIs are stateless, each request is a single method, and the burden is on you as the application builder to stitch multiple requests together to create a useful application.

Postman provides the framework you need to create an API test. Some of the benefits of Postman are:

  • Accessibility – All you need to create end-to-end API requests is the Postman application. There is no need to build a testing environment.
  • Collections – A collection is a grouping of individual API requests. Each request can be manipulated to store values and pass them to the next API request in any order needed.
  • Collaboration – Collections and environments can be imported and exported, making it simple to share files.
  • Environments – An environment is a group of variables. You can use global or specific environment variables. For example, SD-WAN collections for the same SD-WAN environment can be used to decrease human error.
  • Testing – checkpoints can help verify HTTP response status or in validating the response body of a request.

Before moving forward, download Postman from www.postman.com. You can create a free account to get started. Check out Installing and updating from learning.postman.com for additional assistance. After installation is complete, spend some time learning the basics of navigating Postman. Finally, check out Navigating Postman and focus on the following topics:

  • Creating a collection
  • Creating a workspace
  • Running collections
  • Importing and exporting data

Postman setup

Now that we have covered the basics of APIs, REST, VMware SD-WAN Orchestrator APIs, and Postman, let’s build something. For this example, I created a basic bandwidth measurement script that polls the highest utilized link by edge over the last hour. Output is directed to the Postman console. This collection can be used to monitor bandwidth usage and build an enterprise-wide report on bandwidth utilization. This data can be used to increase or decrease bandwidth at locations accordingly.

After building the application yourself, you may see console output like this:

Edge Name: 3400-Hub-HA

Edge Model: edge3800

Edge ID: 17224

Top usage throughput for the last 60 minutes is 0.057 Mbps

To help speed up deployment for you, I have included two files. The postman collection file defining the collection that contains the API requests, pre-request script, and testing. The postman environment file contains the environment variables needed to support to the collection. Go ahead and download both files.

Being JSON formatted, these files are in plain text format. You can open both files in a text editor such as Nano, TextEdit, or Notepad to become more familiar with how Postman structures data using JSON. Importing a collection into Postman is a simple task, as shown below.

  1. Click the File tab, then select Import.
  2. Choose the downloaded collection file and click Open.
  3. Postman will open the collection, and it will appear under the Collections section:

 

To import environment variables, repeat this same process. After the import is complete, ensure that the environment is set to VMware SDWAN and confirm that there are two blank variables, api_key and url. Supply your Orchestrator’s URL, but do not include the protocol. For example, my URL is vco109-usca1.velocloud.net. Type your URL in the INITIAL VALUE and CURRENT VALUE fields. Next, you need to fetch your API token.

You can access the Orchestrator APIs using token-based authentication, irrespective of the authentication mode. Using the Orchestrator UI, go to Administration > Administrators and click your login ID. In the API section, click Actions and choose New API Token. In the pop-up window, complete the fields and click Create.

Select the API token in the field and choose Actions > Download API Token. A Download API Token window displays, and you can copy the token and save it a secure location.  

NOTE: Be sure to copy the token immediately, as this is the only opportunity to view the token.

Go back to Postman and edit the environment variables. Copy and paste the API token to both the INITIAL VALUE and CURRENT VALUE columns.

That’s it for the setup.

Before running the entire collection, let’s ensure that your environment variables and authentication is working. In Postman, under Collections, select the API request GetEnterpriseID, then click the blue Send button. If everything worked correctly, you will see a body response. The field we are most interested in is the id value. My Enterprise ID is 778.

Now click the Tests tab. There is a small bit of code that extracts the Enterprise ID and stores it as an environment variable. The following shows the Postman code to read the body response and set an environment variable:

let responseData pm.response.json();

pm.environment.set("enterpriseId",responseData.id);

Open the environment variables pop-up screen to show the new variable named enterpriseID with the current value set to your Enterprise ID.

This task exemplifies the core of any API application developed in Postman. Each request runs pre-request tests and post-request tests. Each child request in the collection does this. Explore both the pre-request and test sections for each request to see exactly what is happening.

Running a Postman collection

After you have verified that both the collection and environment variables are working, execute the entire collection. Select the collection item Bandwidth Utilization from the left side and click Run on the right side of the screen.

From the Runner tab, click the blue Run Bandwidth Utilization button. As the collection runs, all output is directed to the Postman console. Open the console by clicking the Console button at the bottom of the Postman window.

The collection runs the first two API requests to obtain the Enterprise ID and a list of Edge IDs. The collection then loops the /metrics/getEdgeLinkSeries method for each Edge ID, calculating the peak throughput for the Edge over the last 60 minutes.

Conclusion

The most interesting code for this collection is attached to the GetEdgeBandwidth request. The collection includes both pre-request code and test code. From here, you can add and change the code to suit your needs. For instance, you could aggregate highest usage over multiple WAN links, or you could address error handling when an edge is in a partial active state. Change the output to write to a plain text file, formatted in either JSON or CSV. Consider automating all of this and have the script transformed into Python so that you can pull the data directly into your organization’s existing monitoring platform.

Remember that an API is just a mechanism that is used for computer software on one device to talk to computer software on another device. APIs are used nearly everywhere on the Internet today, and they are finally getting the focus they deserve from networking vendors like VMware and Dell Technologies. We will soon see APIs become the primary means of managing all network devices.

For more examples of VMware SD-WAN Orchestrator API V1 and V2, go to code.vmware.com/samples.

Thanks for reading,
-Curtis Bunch
curtis.bunch@dell.com
https://www.linkedin.com/in/curtisbunch/

Read Full Blog