Getting Started with the NSX SD-WAN by VeloCloud API

As with any proper Software-Defined solution, NSX SD-WAN by VeloCloud has an API to automate against. To be precise, the Orchestrator has an API to automate against. As you might have read in my post about the NSX SD-WAN by VeloCloud Basics, the Orchestrator is the centralized management interface of the SD-WAN.

The Orchestrator provides you with a JSON-RPC API, which means you call it over HTTPS. It’s not a RESTful API, as all calls go through a POST query and authentication is handled in a somewhat strange way (more on that later). There are about 140 API endpoints available, ranging from getting statistics from Edges to executing a failover of an Orchestrator cluster.

Documentation

Centralization of the NSX SD-WAN documentation is still happening, so it’s a bit hard to find documentation. A direct link for the Programmer’s Guide can be found here and the Swagger documentation can be found here.

You’ll find references to the SDK in the guide and Swagger docs. More on the SDK later.

Things you should know

I already mentioned this, but all API calls will be an HTTP POST call. As most APIs have a combination of GET, POST, PUT or DELETE calls - it takes some getting used to.

Something else that is unlike other APIs, is that the authentication works via cookie session. You call the authentication endpoint and if authentication succeeds, a cookie is stored that allows you to call other API endpoints.

My last note before we dive into it is about the role-based access system. The Orchestrator is built up as a 3-tier cake: the top level is Operator; the middle is Partner and lower layer is Customer. The Operator is root and the Partner can manage multiple Customer accounts. This is why you will need to get an Enterprise ID to work with. This Enterprise ID will identify the customer account you’re working with.

Authentication

Let’s get started. Before doing anything else, you need to authenticate and build a session which you can use to call the API further. This is the authentication endpoint:

URL: POST to https://your.vco.url.here/portal/rest/login/enterpriseLogin
Body:
{
  "username": "your@username.tld",
  "password": "yourpassword"
} 

Interpreting the results of this call is going to be a bit unorthodox. Looking at the HTTP status code is not a clear indicator of success or failure. See if you can spot it, here’s a failed login attempt (trimmed header a bit):

HTTP/1.1 302 Found
Content-Length: 0
Set-Cookie: velocloud.message=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: velocloud.session=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: velocloud.message=Login%20failed; Path=/; Secure

Returning the status code 302 and a cookie called ‘velocloud.message’ with the value ‘Login failed’ is what you need to look for. Now on to the login success:

HTTP/1.1 200 OK
Content-Length: 0
Set-Cookie: velocloud.message=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: velocloud.session=s%3Addaa6b418xxxxxxverylongxxxxxgruU5Ig; Path=/; HttpOnly; Secure

Check for status code 200 and store the velocloud.session cookie for future use. Send the cookie with all calls you make from here on out.

Get the Enterprise ID

Most of the API endpoints require that you provide an enterprise ID. There are 2 ways to get it; the fun way and a simple way. For the latter, you can simply log in to the Orchestrator and grab the second number:

That’s your enterprise ID. Now for the fun way; the API. This is also useful when using Partner credentials and searching for a bunch of enterprise IDs. Here’s the call:

URL: POST to https://your.vco.url.here/portal/rest/enterprise/getEnterprise
Body:
{ } 

Don’t forget to provide the authenticated session via the cookie. The result will look like this:

{
  "id": 2,
  "created": "2018-06-24T13:11:38Z",
  "name": "Customer Name",
  "modified": "2018-07-27T15:26:51Z"
  ...omitted a bunch of stuff...
}

The value of id (so 2) is the enterprise ID. Save it and move on to what you actually want to do.

Getting Edges

Time to do something fun! Everything above is about necessary administration to be able to do other things. I’ll show you how to retrieve a list of Edges registered under the customer account with the ID we just saved.

URL: POST to https://your.vco.url.here/portal/rest/enterprise/getEnterpriseEdges
Body:
{
  "enterpriseId": 2
}

You can also look for a specific Edge if you know its ID. If you know the ID and want to filter on that, include “id”: x in the JSON body.

Here is an example of a result that you can expect:

[
  {
    "id": 1,
    "created": "2018-06-24T13:15:30Z",
    "enterpriseId": 2,
    "activationState": "ACTIVATED",
    "softwareVersion": "2.4.1",
    "buildNumber": "R241-20170809-MFG-2",
    "modelNumber": "edge510",
    "deviceFamily": "EDGE5X0",
    "name": "Lostdomain - Home",
    "edgeState": "CONNECTED",
    "edgeStateTime": "2018-08-12T18:54:00Z",
    "systemUpSince": "2018-06-24T13:19:22Z",
    "lastContact": "2018-08-12T19:14:10Z",
    "serviceState": "IN_SERVICE",
    "haState": "UNCONFIGURED",
    "modified": "2018-08-12T19:14:10Z"
  },
  {
    "id": 2,
    ...etc...
  }
]

Having pruned a lot of the resulting output, there is a lot of useful information there.