The API for VCF is hands down, one of the most powerful in the industry. Allowing you to accomplish everything from scheduling backups, to rotating certificates and passwords across the deployment, to deploying an NSX Edge Cluster complete with Tier-0 and Tier-1 routers configured!
While the Developer Center is a great place to start and try out API’s, making it part of your enterprise automation/orchestration systems should be the goal. For that you’ll want the VCF API swagger file to import into your API Orchestration engine. While this isn’t able to happen straightaway, it’s easy to complete with just a few simple tweaks.
A customer contacted me with this exact request and while I was able to get them the URL to download the swagger.json for VCF there were a few issues that were stopping them from importing it. I looked into it further using the awesome tool here: https://editor.swagger.io/ and was able to address the problems and get it imported!
For this blog, I’ll use Postman for my example API Orchestration engine, but know that we’re only doing to modifications to the swagger.json to make it compliant with the swagger 2.0 schema so it’s able to be imported to any system that can accept this.
First, we’ll need to get the swagger.json from the SDDC Manager. This can be obtained by using a web browser, wget, invoke-webrequest and the like from this URL: https://<sddcmanager-fqdn>/ui/assets/spec/external/swagger.json
Once you have this, you’ll want to open a new tab and navigate to https://editor.swagger.io/ and click File-> Clear Editor. After it’s cleared, paste or import the JSON file we just got before. It may pop up and ask you if you’d like to convert your JSON to YAML, say yes and wait several seconds and you’ll see a red Errors box pop up on the right.
Let’s take 4 steps to make this work like a champ when importing!
- Add the ‘version’ property to the info section, once you insert line 5 below, wait several seconds again for the parser to update the Errors box. The version needs to be a string, I use the VCF version here as an example.
2. This next one is an issue because swagger sees both certificate-authorities lookups as duplicates as it doesn’t recognize the variable (defined in the {}) as being a differentiator during parsing. Due to this we’ll need to make a choice and remove one of the certificate-authorities lookups. Currently you can only have (1) certificate authority defined in VCF so this makes my decision easy and I remove the caType lookup, note your line numbers may be different if you have not does step 1 yet.
3. Then you’ll need to change the type under the personalities files upload to a string. ***I’m not 100% sure if this will break the API call, as I’m unable to fully test. However the initial setting of “files” is not one of the allowed values. In looking at the API examples it would seem this change would be correct.
4. The final change you should make, is not actually required but will probably make your, or your API Orchestrator admin(s) lives easier. Up at the top of the file, change the host: field from it’s default of sfo-vcf01.rainpole.io to the fqdn for your SDDC Manager.
That should do it, now all you need to do is go to File -> Convert and save as JSON. Or if your API Orchestration wants YAML that’s fine to! Then import into your API Orchestration system and enjoy!
In Postman, I simply and to click “Import” in the Collections tab and then select the file we just saved from the Swagger.io editor and then Import again.
Now I’ve got a list of all the API calls, as well as my baseUrl defined as a variable. This includes all the example data, specs and responses you’d see in the Developer Center as well!
Hope you enjoyed reading and realize the power and ease that API’s and automation can bring to you and your VCF deployment!