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": "[email protected]",
  "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.



Share the wealth!

14 Comments

  1. Thanks for posting this article. There aren’t too many resources re: the VeloCloud Orchestrator SDK/API. Looking fwd to more!

  2. What are you using to post? Is that your actual code above? I have been using CURL which is not as easy as you make it look above. Thanks

    • Martijn

      September 17, 2018 at 19:12

      Yikes, I need to do something about the background colors in the comment, so hopefully you can read this…

      The above examples are made using the Postman REST client, but it’s not literal screenshots to save space. CURL can be used, but you need to make sure you use the “–cookie-jar cookies.file” parameter to save the session between calls.

  3. Hi Martijn,
    could you please tell me how to use SDK/API for VeloCloud? what I have to install ? if you can step by step . thank you in advvance

    • Martijn

      October 26, 2018 at 17:17

      Hi Dri,

      I have a SDK post in the pipeline (but soo many things to do), but in the meantime you should be able to get documentation from your VeloCloud team.

  4. Hello,

    In Postman, once I run the /enterprise/enterpriseLogin it stores the cookie, allowing me to make subsequent calls without setting it.

    However, when I export my API calls into Python, it does not translate the stored session cookie in Postman’s provided Python(requests) code.

    Is there a way to pass the velocloud.session cookie I have received from enterprise/enterpriseLogin into my header?

    I am running Python 3.7.2, so the code provided from setup.py to use the SDK Programmer’s Guide is not helpful (as it only supports Python 2.X).

    Any assistance would be greatly appreciated!

  5. Mostafa Katary

    June 13, 2019 at 03:15

    Hello Martijn,

    I am not able to perform the first GET call using postman (Status: 404 Not Found) to get the cookies, https://VCO/portal/rest/login/enterpriseLogin with username and password as Basic Auth. not sure what could be the issue.

    • Martijn

      June 23, 2019 at 17:45

      Hi,

      You are replacing ‘https://VCO’ with your VCO address, right? The API endpoint still exists, this should still work.

  6. Hi, nice tutorial.
    Do you have the new version of programmer guide? or do you know where can I find it?

    Thanks!

    • Martijn

      September 19, 2019 at 08:33

      Looks like it’s not available on the public docs website yet, try to contact your VMware sales rep to get the latest version.

  7. I wasn’t able to get a list of all enterprise ids using the ‘getEnterprise’ post with the body set to ‘{ }’ that you list in your examples. I get this error returned. Is this still supported?

    {
    “error”: {
    “code”: -32603,
    “message”: “validationError”,
    “data”: {
    “valid”: false,
    “error”: [
    {
    “code”: “GET_ENTERPRISE_0001”,
    “message”: “Request params must include valid enterprise id”,
    “path”: “id”
    }
    ],
    “warning”: []
    }
    }

    • Martijn

      September 7, 2021 at 10:50

      This post is over 3 years old, so things might have changed, yes. I can’t say for sure without knowing the exact call you’re doing.

Leave a Reply

Your email address will not be published. Required fields are marked *

© 2024 Lostdomain

Theme by Anders NorénUp ↑