Introducing OpenAPI Specification for VMware Cloud Foundation 9.0

Navigating long API documentations, piecing together curl commands, and relying on trial and error while learning Application Programming Interface (APIs) can be a frustrating experience. We all have been there. OpenAPI solves this by providing a complete, interactive catalog of available endpoints when its specification is imported into API client tools like Postman. This includes clear details on methods, parameters, authentication, and example payloads. 

For cloud admins and developers working on VMware Cloud Foundation (VCF), this approach accelerates the API learning curve. Instead of interpreting documentation, you can consume OpenAPI documentation and quickly get up to speed with VCF APIs. 

OpenAPI Specification in VMware Cloud Foundation 9.0 

At Broadcom, we are building VMware Cloud Foundation with a developer-first mindset, and the OpenAPI initiative is at the forefront of realizing this goal. By standardizing our APIs with OpenAPI Specification, we’re not only simplifying how developers interact with VCF, but also empowering them to build, integrate, and automate with greater speed, consistency, and confidence. 

Starting with VCF 9.0 we are publishing OpenAPI specifications for the following components. 

• VMware vSphere
• VMware Cloud Foundation SDDC Manager
• VMware Cloud Foundation VCF Installer
• VMware Cloud Foundation VCF Operations
• VMware vSAN Data Protection (vSAN DP)

Developer Portal – Download VCF 9.0 OpenAPI Specifications
Github Repository – VCF 9.0 OpenAPI Specifications

What is OpenAPI

APIs (Application Programming Interface) are ubiquitous ways of providing interaction between software systems and services. APIs can vary based on the communication protocol they use (such as HTTP, gRPC, or GraphQL) and how they are accessed. Among the various API styles, REST APIs have emerged as the most widely adopted—thanks to their simplicity, scalability, and wide compatibility across platforms.

A REST API typically consists of a set of methods (the types of requests that can be made to the server), input parameters, and structured responses. These elements allow an API client to send a request and receive a meaningful response—for example, a cloud management system querying virtual machine details over the network.

Before diving into the OpenAPI Specification, it’s important to understand the broader API lifecycle. Building an API is not just about enabling communication between a client and a server—it’s about ensuring that APIs are consistent, discoverable, easy to understand, integrate, and test. For API consumers, this translates to faster adoption and fewer errors. For API providers, it ensures scalability, reusability, and language-agnostic integration.

This is where the OpenAPI Specification (OAS) becomes crucial. It provides a standard, machine-readable format to define APIs, effectively bridging the gap between API providers and consumers. OpenAPI helps ensure that APIs are not just functional—but also well-documented, testable, and automation-friendly across the development lifecycle.

Introduction to OpenAPI Specification

The basic building blocks of OpenAPI specification documents are as below.  ​​

Construct	Purpose
openapi	Specifies OpenAPI version
info	API metadata
servers	API base URLs
paths	Endpoint definitions
components	Reusable pieces like schemas & parameters
parameters	Input values in URL/path/header/query
requestBody	Payload structure for POST/PUT
responses	Response format & status codes
security	Authentication mechanisms
tags	Logical grouping of endpoints
externalDocs	Link to extra documentation

For example, let us look at the OpenAPI specification document, vcenter.yaml.

Openapi, info, servers 

This is the metadata information about OpenAPI specification version info and its title, Server URL to which API request will be sent to. 

• OpenAPI version
• Title, version of the API
• Base URL for API endpoints

Paths – Resource Endpoints

• Path /vcenter/datacenter is the resource endpoint
  
• GET: Defines the HTTP method supported on this path
  
• All API interactions are defined under paths

Operation – the HTTP method (get here)

Returns information about at most 1000 visible (subject to permission checks) datacenters in vCenter.

  operationId: list

• tags: Helps organize and group related APIs in documentation
  
• summary: One-liner explaining what this endpoint does
  
• operationId: A unique identifier for this operation (useful in codegen)

Parameters – Input for this API operation

• Used to filter the datacenter list
  
• filte.names: array of names to filter
  
• filter.datacenters: array of IDs (like Managed Object References)
  
• in: query: means these are query parameters
  
• required: false: optional filters

This demonstrates parameter definition, data type, and location

Responses – Output that API sends

• For HTTP status code 200 (OK), the API returns:
  
  • A JSON object with a key called value
    
  • That key holds an array of datacenter summaries
    
• Each item in the array refers to a reusable schema

Components.schemas – Reusable building blocks

Summary of Building Blocks with This Example

Building Block	In This Example
openapi	“3.0.3” at the top of the spec
info	Title, version of the vCenter API
servers	Base URL with variable
paths	Defines /vcenter/datacenter
operation	get method for listing datacenters
tags	Categorized under vCenter.Datacenter
parameters	filter.names and filter.datacenters
responses	Describes response for HTTP 200
schema	JSON object with value
$ref	Points to reusable schema
components.schemas	VcenterDatacenterSummary object definition

Advantages and Use cases of OpenAPI 

Generate Postman Collection through OpenAPI

Postman is a popular API client that helps developers create, share, test, and document APIs. A Postman Collection is a group of saved API requests, along with their associated scripts, variables, and tests. Manually creating a Postman Collection for a complex API can be a tedious and error-prone process. This is where OpenAPI comes in handy. Follow below steps to generate vSphere Automation API Collection using OpenAPI Specification.

1. Visit developer documentation and download the OpenAPI specification zip file. Alternatively you can download via VMware Github API Spec repository. 
2. Open Postman 
3. Click on the import Icon. 

4. Click on File to import OpenAPI specification. 

5. Browse the path where OpenAPI specifications are available

6. Wait for the Import Operation to complete. 

7. Select postman collection and click Import.

8. Wait for Import to be completed. 

As you can see the import is successful and you have vSphere Automation API collection ready to be used. 

Use vSphere Automation API Postman Collection

1. Authentication – To authenticate expand collection vSphere Automation API -> Session and Select Cis.Session create

2. Click on the Authorization Tab and Set Username and Password for basic authentication.
   1. Click on Authorization
   2. Hover {{basicAuthUsername}} and enter vCenter username. //this is automatically created for you by OpenAPI to simplify the operations 
   3. Optional, It is better to create an environment and store the variables for further use. Click Create 
   4. do the same for {{basicAuthPassword}}

3. Click on Send to invoke the api. 

Now you have the Authentication token, Let us list available Virtual Machines in vCenter. 

1. To list Virtual machines browse vSphere Automation API -> 

2. Click on GET Vcenter.VM list, Go to Authorization and Provide the Authorization Key which we generated while creating the vcenter server session. 

3. By default we are passing all the parameters. Let us remove the parameters from the request body.
   1. Click on Params tab
   2. Deselect all the parameters

4. Click Send 

We’ve just demonstrated how a Postman collection can be automatically generated using OpenAPI, which offers significant value to Cloud Admins. This approach substantially reduces the API learning curve. 

Generate Client Side SDK using OpenAPI

We announced the general availability of a unified VCF SDK for Python and Java. However, There might be a situation where you want to use VCF APIs with programming languages other than Python and Java, For example .Net C#. Since there is no .Net C# SDK available you can generate your own using OpenAPI. Let us take one such example of generating .Net C# SDK from an OpenAPI Specification using OpenAPI tool Kiota.

1. Download and Install Kiota. 

2. Run below command to generate a SDK client for vSphere Automation API using OpenAPI specification

The OpenAPI specification for VMware Cloud Foundation (VCF) APIs simplifies and accelerates developer workflows for automation, integration, and innovation. This standardized format allows easy exploration and interaction with VCF APIs using familiar tools and SDK generators, reducing onboarding time and ensuring consistency. 

References and Learning Resources

Github Repository – VCF 9.0 OpenAPI Specifications

Developer Portal – Download VCF 9.0 OpenAPI Specifications

OpenAPI Initiative

What is OpenAPI

Microsoft Kiota 

OpenAPI Generator

Introducing a Unified VCF 9.0 SDK for Python and Java