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.
September 14, 2018 at 17:25
Thanks for posting this article. There aren’t too many resources re: the VeloCloud Orchestrator SDK/API. Looking fwd to more!
September 17, 2018 at 18:04
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
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.
October 26, 2018 at 17:12
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
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.
March 22, 2019 at 17:42
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!
March 23, 2019 at 16:02
Hi Tyler,
Postman does indeed make that easy and stores and reuses cookies by default. You need to do that manually in Python by using the cookiejar principle. It kind of depends what Python library you’re using, but here’s a few tips:
https://www.programcreek.com/python/example/108316/http.cookiejar.CookieJar
http://itspg.logdown.com/posts/1719-use-python3-to-login-http-web
https://code.tutsplus.com/tutorials/using-the-requests-module-in-python–cms-28204
March 25, 2019 at 14:14
Thank you so much for the assistance Martijn! I was able to manually set the cookie in the headers as ‘Cookie’ instead of ‘Set-Cookie’.
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.
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.
September 10, 2019 at 17:53
Hi, nice tutorial.
Do you have the new version of programmer guide? or do you know where can I find it?
Thanks!
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.
July 14, 2021 at 20:29
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”: []
}
}
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.