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 documentation - https://code.vmware.com/apis/1115/velocloud-sdwan-vco-api
• Orchestrator API V2 documentation - https://developer.vmware.com/docs/vmware-sdwan-rest/latest/

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.

• Bandwidth Utilization.postman_collection.json
• VMware SDWAN.postman_environment.json

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/

The Versa Networks SD-WAN solution solely relies on MP-BGP for route distribution. This is achieved via the controllers acting as route reflectors through the secure overlay control channel that each CPE maintains on a per tenant basis with SD-WAN Controllers. Versa Networks SD-WAN solution does not need IGP protocols for MP-BGP next-hop resolution since each CPE are back-to-back/directly connected to each other using secure overlay forwarding tunnels.

The main features of the Versa Networks SD-WAN routing solution are listed below:

• Multiple MPBGP instances each configured within a routing-instance or global hierarchy
• Each MPBGP instance corresponds to a tenant and can support multiple VRFs per tenant
• SD-WAN Controller (Route reflector) reflects the routes to other branches and send to other controllers as well (Route Reflector meshing).
• The route reflector can be different than Controllers where required

Various topologies can be supported on a per VRF basis. These include:

• Hub & Spoke
• Partial-mesh
• Full-mesh
  
  
  

Figure 1: Dell EMC VEP SKUs for Versa SD-WAN (Versa software preloaded in Dell manufactory)

Figure 2: Versa software overview and highlights

  Figure 3. Versa control plane, orchestrator and MANO layer

Figure 4. External LTE modem for Dell EMC Versa SD-WAN solutions

Additional Resources 

Dell Technologies SD-WAN/uCPE Solutions and Technologies

Dell Technologies ADVA uCPE Solutions

Over the course of Wide Area Network (WAN), the landscape has dramatically changed through many stages of innovations, from frame relay, ATM, X.25, SDH optical networks, etc. and MPLS. The latest stage, which we are in now, is Software Defined-WAN (SD-WAN).

1. What is SD-WAN/uCPE?

In a nutshell, SD-WAN is running network routers in Virtual Machine (VM), dynamically and intelligently by routing and directing network traffics to the most optimized WAN network path. For example, MPLS, broadband Internet, or cellular networks. 

Back in the old days, corporate datacenters and branches were primarily connected through MPLS circuits amongst different geographic locations. This new network architecture solves the problem to access on-prem applications hosted in datacenters such as database, web server, mail server, etc. The following figure describes this process.

Figure 1: Branch office to central office in the past

As cloud and virtualization are taking off everywhere, software applications are being virtualized, outsourced, scaled out, and hardened to meet more stringent standards and requirements. Today’s network traffics are driven by software applications that can be characterized by the following features:

• Cloud applications that are fundamentally driving WAN from static to on-demand.
• Prevalent cellular network (LTE and 5G) provides an efficient and faster network path between user, branch, and edge to data center or other peers.
• Internet-of-Things (IoT) is driving need for Edge processing, bandwidth, and security
• Devices and Things driving competitive advantage, increase Edge processing, security, and connectivity.
• Collocated datacenters close to fiber exit provide advantages to reroute network traffics based on adjacent disembark network points (see the diagram below).
• Dell Technologies strongly believes and promotes open and disaggregated model to drive the separation of hardware and hardware infrastructures, software infrastructures, and software applications. Everyone can focus on their own core competence.  As an example, Dell worked closely with many SD-WAN software vendors, VMware/VeloCloud, Versa Networks, and ADVA Optical to provide customers with choices and flexibilities.

Figure 2: Branch office to central office now 

To manage the network and route traffic more efficiently, the router must probe application traffics into payload layers to figure out which applications this packet belongs to. For example, mail access traffic, web server traffic, database traffic, or others. With that level of application knowledge, the router can then redirect the traffics to a proper network path such as MPLS, broadband Internet, or LTE/5G MEC edges, for example, database hosted in a corporate datacenter will go through MPLS circuit whereas Microsoft Outlook mail server hosted in Azure cloud will be routed to the broadband Internet circuit. IoT or smart phone traffics can be routed through LTE/5G network to the closest Edge network.

Keep in mind that these probing and routing policies are constantly changing, so the better choice is to run probing/routing/directing traffic processes in virtual machine (VM) instead of an embedded firmware running on a dedicated hardware-based router system. To push the integration to another level, one can easily implement more VMs on the same physical system, that’s where the uCPE solution comes to play. For illustration, see the figures below. 

Figure 3: uCPE revolution: From racks to a single box 

Figure 4: uCPE block diagram

Physical Network Function (PNF) are the traditional network equipment like routers, firewall appliances, and VPN servers. PNF vendors are transitioning the physical equipment to VMs. By running these VMs in a hypervisor, which is hosted on one hardware computer, and integrating them together through the industry standard protocols such as service chaining, customers can successfully run multiple VM based Virtual Network Functions (VNFs) in one physical unified Customer Premises Equipment (uPCE) server. Therefore, one server can replace a rack of hardware appliances, reduce the hardware footprint, power consumption, and more. 

2. Tenets of SD WAN/uCPE technologies

• In contrast to regular router and switches, SD-WAN solutions follow the same rule of Software Defined Network (SDN) technologies. In SD-WAN, control plane is completely separated from the data plane. The control plane is part of the SD-WAN orchestration and Management Automation and Orchestration (MANO) layer. The data plane stays either in a physical server or VM. All the configuration and traffic routing are done at the control plane.  That way, the physical system can be easily replaced at any time since the configuration data and other traffic control related information are kept at control plane and can be restored to the new replaced physical system. 
• SD-WAN traffic redirecting and probing are implemented in VMs, hence its name Network Function Virtualization (NFV). With that approach, it can be easily performed on a physical server, on a private cloud, hybrid cloud, or public cloud, such as AWS, Azure, and Google Cloud. It can also scale out to accommodate dynamic, eventful, and bursty traffics by adding more hardware resources to VM.
• Zero Touch Provisioning (ZTP): With SD-WAN orchestrator, customers can ship an unconfigured physical server directly to any deployment sites and get it automatically and securely configured through the orchestrator.
• Disaggregated and open architecture, with software agnostic hardware, allowing everyone to focus on their own core competence. This maximizes the choices for customers to address their unique technical and commercial needs with flexibility and investment protection, without requiring forklift upgrades. 

3. Why choose Dell EMC for SD-WAN/uCPE technologies?

Dell EMC has operated a build to order supply chain strategy allowing us to deliver the latest technology to our customers at the right price and at the right time. The strength of our supply chain is an important factor in our ability to deliver project cost efficiencies to our customers. 

Dell EMC's vision is to provide our customers with an open, disaggregated set of solutions from core to edge, allowing them to remove proprietary infrastructure, decrease CapEx, and automate operations as they deliver new services and applications to their end customers. 

Dell EMC is a global leader in compute, storage, and Open Networking infrastructure. Dell EMC SD-WAN/uCPE solutions leverage the full suite of hardware and software platforms to provide a complete end to end solution by addressing the requirements in a simplified manner. By leveraging a large ecosystem with leaders in their respective space, Dell EMC SD-WAN/uCPE team engages with these partners to create simple, replicable, and Ready to Use solutions. 

Dell EMC provides 100% open architecture and is committed to progressing "open systems" at both hardware and software levels. The solutions provides the building blocks for modern network infrastructure. Systems can scale independently to accommodate and optimize efficiency for network operations. 

Additional Resources

Dell Technologies ADVA uCPE Solutions

Dell Technologies Versa SD-WAN Solutions and Technologies