Exploring the Intersight API with a Python-Based Schema Browser

Introduction

When developing automation for Cisco Intersight, understanding the API structure is crucial. The Intersight OpenAPI v3 specification contains over 5,000 schemas across 575,000+ lines of YAML—a daunting document to navigate manually. This article introduces a Python-based tool that makes exploring this specification efficient and practical.

The Challenge

Developing PowerShell functions for Intersight requires deep knowledge of:

Object properties and their types
Required vs. optional fields
Relationship hierarchies (MoMoRef patterns)
Enum values and defaults
Inheritance structures through allOf references

Without proper tooling, developers must:

Search through massive YAML files manually
Trace inheritance chains across multiple schema definitions
Guess which properties are relationships vs. simple types
Trial-and-error to find mandatory properties

This slows development and increases the chance of errors.

The Solution: `get_intersight_api_reference.py`

The tool provides a command-line interface for querying the OpenAPI specification with features specifically designed for API exploration and development workflows.

Key Features

1. Schema Discovery

List all 5,394 available schemas
Filter by module prefix (e.g., all vnic.* types)
Quick search for specific object types

2. Property Analysis

Automatic inheritance resolution (allOf chains)
Clear identification of relationships vs. simple properties
Read-only property detection
Enum value extraction
Default value display

3. Relationship Mapping

Automatic detection of MoMoRef patterns
Distinction between single and array relationships
Full relationship type resolution

4. Export Capabilities

JSON export for further processing
Integration with tools like jq
Documentation generation

Installation and Setup

Prerequisites

The tool requires Python 3 and the PyYAML library:

1
2
3
4
5
# Install dependencies
pip install pyyaml

# Make the script executable (optional)
chmod +x get_intersight_api_reference.py

Download the OpenAPI Specification

The tool requires the Intersight OpenAPI v3 specification file. Download it from the official Cisco Intersight API documentation:

Option 1: Download via Browser

Visit the Intersight API Documentation
Navigate to the API reference section
Look for the “Download OpenAPI Specification” link
Download the YAML file (typically named intersight-openapi-v3-<version>.yaml)
Place it in your workspace directory

Option 2: Download via Command Line

1
2
3
4
5
6
7
8
# Download the latest OpenAPI spec (replace URL with current version)
curl -O https://intersight.com/apidocs/downloads/intersight-openapi-v3.yaml

# Or use wget
wget https://intersight.com/apidocs/downloads/intersight-openapi-v3.yaml

# Verify the download
ls -lh intersight-openapi-v3*.yaml

Note: The specification file is approximately 180 MB and contains 575,000+ lines. Make sure you have sufficient disk space.

Option 3: From Intersight PowerShell SDK

If you have the Intersight PowerShell SDK installed, the OpenAPI specification is usually included in the SDK directory:

1
2
3
4
5
6
# Find the SDK installation directory
Get-Module -ListAvailable Intersight* | Select-Object -ExpandProperty ModuleBase

# The OpenAPI spec is typically in the SDK's documentation or examples folder
# Example path (varies by installation):
# C:\Program Files\WindowsPowerShell\Modules\Intersight.PowerShell\1.0.11\

Verify the Setup

After downloading the specification, verify everything is ready:

1
2
3
4
5
6
7
8
# Check Python version (3.6+ required)
python3 --version

# Verify PyYAML is installed
python3 -c "import yaml; print(yaml.__version__)"

# Test the tool with the downloaded spec
python3 get_intersight_api_reference.py -l | head -20

The script auto-detects the OpenAPI specification file in your workspace. If multiple files exist, it uses the first match and warns you. You can explicitly specify the path with the -s option:

`1`	`python3 get_intersight_api_reference.py -s /path/to/intersight-openapi-v3.yaml -l`

Basic Usage

List All Available Schemas

`1`	`python3 get_intersight_api_reference.py`

Output:

1
2
3
4
5
6
7
8
9
=== Available Object Types ===

  aaa.* (15 schemas)
  adapter.* (45 schemas)
  ...
  vnic.* (28 schemas)
  workflow.* (35 schemas)

Total: 5394 schemas

Filter Schemas by Module

`1`	`python3 get_intersight_api_reference.py -l vnic`

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
=== Available Object Types ===

  vnic.*
    - vnic.BaseEthIf
    - vnic.Cdn
    - vnic.EthAdapter
    - vnic.EthAdapterPolicy
    - vnic.EthIf
    - vnic.EthNetworkPolicy
    - vnic.EthQosPolicy
    - vnic.VnicTemplate
    ...

Total: 28 schemas

Explore a Specific Schema

`1`	`python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p`

This displays:

Description from the API documentation
Inheritance hierarchy
Required properties
All properties with types and descriptions
Markers for relationships and read-only fields

Focus on Relationships

`1`	`python3 get_intersight_api_reference.py -t vnic.VnicTemplate -r`

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
=== vnic.VnicTemplate ===

Relationship Properties:

  EthAdapterPolicy
    Type: vnic.EthAdapterPolicy.Relationship
    Description: A reference to a vnicEthAdapterPolicy resource.

  FabricEthNetworkGroupPolicy
    Type: fabric.EthNetworkGroupPolicy.Relationship
    Description: An array of relationships to fabricEthNetworkGroupPolicy resources.

  MacPool
    Type: macpool.Pool.Relationship
    Description: A reference to a macpoolPool resource.

Total Properties: 38
Relationships: 11

Export for Processing

1
2
3
4
python3 get_intersight_api_reference.py \
  -t vnic.VnicTemplate \
  -p \
  -o vnic-template.json

The JSON output can be processed with tools like jq:

1
2
3
4
5
# Extract only relationship names
jq -r '.relationships | keys[]' vnic-template.json

# Get all required properties
jq -r '.required[]' vnic-template.json

Real-World Development Workflow

Let’s walk through developing a new PowerShell function using this tool.

Scenario: Clone a vNIC Template

We need to create Copy-IntersightVnicTemplate that clones a vNIC template with cluster-specific configuration.

Step 1: Understand the Schema

`1`	`python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p`

Key Findings:

Required: ClassId, ObjectType
Name property: String type (for the new template name)
Inherits from: vnic.BaseEthIf (we get base properties too)
Relationships: 11 different policy references

Step 2: Identify Mandatory Relationships

1
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -r | grep -i "mandatory\|required"

From the descriptions, we find:

FabricEthNetworkControlPolicy is mandatory
FabricEthNetworkGroupPolicy is required (at least 1)

Step 3: Understand Network Group Policy

`1`	`python3 get_intersight_api_reference.py -t fabric.EthNetworkGroupPolicy -p`

Key Properties:

VlanSettings - VLAN configuration object
Organization - Must use original organization (not template’s)!

Step 4: Check Property Types

For FabricEthNetworkGroupPolicy:

1
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p | grep -A 3 "FabricEthNetworkGroupPolicy"

Output:

1
2
3
  FabricEthNetworkGroupPolicy [REL]
    Type: array of fabric.EthNetworkGroupPolicy.Relationship
    Description: An array of relationships...

This tells us:

It’s an array (not a single reference)
We need to create multiple MoMoRefs
Each references a FabricEthNetworkGroupPolicy

Step 5: Implement in PowerShell

Armed with this knowledge, we write:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
function Copy-IntersightVnicTemplate {
    param(
        [Parameter(Mandatory)]
        [PSCustomObject]$SourceVnicTemplate,

        [Parameter(Mandatory)]
        [int]$ClusterNumber
    )

    # Clone Network Groups (array relationship)
    $fabricEthNetGroupPolicies = @()
    foreach ($networkGroup in $SourceVnicTemplate.FabricEthNetworkGroupPolicy) {
        $clonedNetworkGroup = Copy-IntersightEthernetNetworkGroup @params

        $moMoRef = Initialize-IntersightMoMoRef `
            -ClassId 'MoMoRef' `
            -ObjectType 'FabricEthNetworkGroupPolicy' `
            -Moid $clonedNetworkGroup.Moid

        $fabricEthNetGroupPolicies += $moMoRef
    }

    # Copy mandatory FabricEthNetworkControlPolicy (single relationship)
    $controlPolicyRef = Initialize-IntersightMoMoRef `
        -ClassId 'MoMoRef' `
        -ObjectType 'FabricEthNetworkControlPolicy' `
        -Moid $SourceVnicTemplate.FabricEthNetworkControlPolicy.Moid

    # Create new vNIC Template
    $newVnicParams = @{
        Name = "vNIC-CL{0:00}-Template" -f $ClusterNumber
        ClassId = 'vnic.VnicTemplate'
        ObjectType = 'vnic.VnicTemplate'
        FabricEthNetworkGroupPolicy = $fabricEthNetGroupPolicies
        FabricEthNetworkControlPolicy = $controlPolicyRef
    }

    New-IntersightVnicVnicTemplate @newVnicParams
}

The tool prevented common errors:

❌ Treating array relationship as single value
❌ Missing mandatory FabricEthNetworkControlPolicy
❌ Wrong ObjectType in MoMoRef
❌ Forgetting required properties

Advanced Use Cases

1. Validate Parameter Sets

1
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p | grep -A 3 "SwitchId"

Output:

1
2
3
4
  SwitchId
    Type: string
    Enum: None, A, B
    Default: None

Translate to PowerShell:

1
2
3
[Parameter()]
[ValidateSet('None', 'A', 'B')]
[string]$SwitchId = 'None'

2. Document API Changes

Export schemas before and after SDK updates:

1
2
3
4
5
6
7
8
# Before update
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -o before.json

# After update
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -o after.json

# Compare
diff before.json after.json

3. Generate Documentation

Create property reference tables:

1
2
3
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p | \
  grep -A 2 "^  [A-Z]" | \
  grep -v "^--$" > vnic-template-properties.txt

4. Bulk Analysis

Find all mandatory properties across multiple schemas:

1
2
3
4
5
6
for type in vnic.VnicTemplate vnic.EthIf fabric.EthNetworkGroupPolicy; do
    echo "=== $type ==="
    python3 get_intersight_api_reference.py -t $type -p 2>/dev/null | \
        grep -A 10 "Required Properties"
    echo ""
done

Technical Deep Dive

Inheritance Resolution

The tool automatically resolves complex inheritance chains. For example, vnic.VnicTemplate:

1
2
3
4
5
6
7
8
9
vnic.VnicTemplate
  ↓ allOf
  ├─ vnic.BaseEthIf
  │  ↓ allOf
  │  ├─ policy.AbstractPolicy
  │  │  ↓ allOf
  │  │  └─ mo.BaseMo
  │  └─ Inline definition
  └─ Inline definition

All properties from parent schemas are merged and displayed as a single, flat list. This eliminates the need to manually chase references through the YAML file.

Relationship Detection Algorithm

Properties are identified as relationships when:

Type ends with .Relationship
- Example: vnic.EthAdapterPolicy.Relationship
Type is MoMoRef or mo.MoRef
- Direct managed object references
Array items match above criteria
- Example: array of fabric.EthNetworkGroupPolicy.Relationship

This allows the tool to automatically separate data properties from object references, crucial for understanding the API structure.

Performance Considerations

First Run (~5-10 seconds)

YAML parsing of 575,110 lines
Schema indexing
Inheritance graph building

Subsequent Queries (instant)

In-memory lookup
Pre-built inheritance chains
Cached schema definitions

For development workflows with multiple queries, consider:

1
2
# Keep an interactive Python session
python3 -i get_intersight_api_reference.py

Property Markers Explained

The tool uses visual markers for quick identification:

Marker	Meaning	Implication
[REL]	Relationship	Requires MoMoRef creation
[RO]	Read-Only	Cannot be set during creation/update
→	Reference	Shows the target object type

Example output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  Name
    Type: string
    Description: Name of the vNIC template.

  MacPool [REL]
    Type: → macpool.Pool.Relationship
    Description: A reference to a macpoolPool resource.

  AccountMoid [RO]
    Type: string
    Description: The Account ID for this managed object.

Integration with CI/CD

Pre-Commit Hook

Validate that new functions reference valid object types:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#!/bin/bash
# .git/hooks/pre-commit

# Extract ObjectType references from modified PowerShell files
git diff --cached --name-only | grep '\.ps1$' | while read file; do
    grep -oP "ObjectType\s*=\s*'\K[^']+" "$file" | while read objtype; do
        python3 get_intersight_api_reference.py -t "$objtype" -p > /dev/null 2>&1
        if [ $? -ne 0 ]; then
            echo "Error: Invalid ObjectType '$objtype' in $file"
            exit 1
        fi
    done
done

Documentation Generation

Generate API reference documentation automatically:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#!/bin/bash
# generate-api-docs.sh

SCHEMAS=("vnic.VnicTemplate" "vnic.EthIf" "fabric.EthNetworkGroupPolicy")

for schema in "${SCHEMAS[@]}"; do
    python3 get_intersight_api_reference.py \
        -t "$schema" \
        -p \
        -o "docs/api-reference-${schema}.json"
done

Comparison with Alternatives

vs. Manual YAML Search

Aspect	Manual Search	This Tool
Find schema	`grep` through 575K lines	Instant lookup
Inheritance	Manual chain following	Automatic resolution
Relationships	Visual inspection	Auto-detected
Export	Copy/paste	JSON output
Speed	Minutes per schema	Seconds per schema

vs. Web Documentation

Aspect	Web Docs	This Tool
Offline access	❌	✅
Version-specific	May mismatch SDK	Exact match to SDK
Scriptable	❌	✅
Bulk queries	❌	✅
Export	Manual copy	JSON/programmatic

vs. IDE Schema Hints

Aspect	IDE	This Tool
Requires SDK installation	✅	❌
Shows relationships	Partial	Complete
Shows inheritance	No	Yes
Bulk analysis	No	Yes
Export	No	Yes

Common Patterns and Idioms

Pattern 1: Single Relationship Property

Schema:

1
2
3
4
5
{
  "MacPool": {
    "ref": "macpool.Pool.Relationship"
  }
}

PowerShell Implementation:

1
2
3
4
5
6
7
8
if ($SourceTemplate.MacPool) {
    $macPoolRef = $SourceTemplate.MacPool
    $moMoRef = Initialize-IntersightMoMoRef `
        -ClassId 'MoMoRef' `
        -ObjectType 'MacpoolPool' `
        -Moid $macPoolRef.Moid
    $params['MacPool'] = $moMoRef
}

Pattern 2: Array of Relationships

Schema:

1
2
3
4
5
6
{
  "FabricEthNetworkGroupPolicy": {
    "type": "array",
    "items": "fabric.EthNetworkGroupPolicy.Relationship"
  }
}

PowerShell Implementation:

1
2
3
4
5
6
7
8
9
$moMoRefs = @()
foreach ($policy in $SourceTemplate.FabricEthNetworkGroupPolicy) {
    $moMoRef = Initialize-IntersightMoMoRef `
        -ClassId 'MoMoRef' `
        -ObjectType 'FabricEthNetworkGroupPolicy' `
        -Moid $policy.Moid
    $moMoRefs += $moMoRef
}
$params['FabricEthNetworkGroupPolicy'] = $moMoRefs

Pattern 3: Enum Validation

Schema:

1
2
3
4
  SwitchId
    Type: string
    Enum: None, A, B
    Default: None

PowerShell Implementation:

1
2
3
[Parameter()]
[ValidateSet('None', 'A', 'B')]
[string]$SwitchId = 'None'

Pattern 4: Conditional Mandatory Properties

Some properties are mandatory only in certain contexts. The tool shows all required properties, but descriptions reveal context:

`1`	`python3 get_intersight_api_reference.py -t vnic.EthIf -p`

Look for phrases like:

“required when…”
“mandatory for…”
“must be specified if…”

Troubleshooting

Schema Not Found

Problem:

`1`	`Error: Schema 'vnic.Template' not found`

Solution:

1
2
3
4
5
# Search for similar schemas
python3 get_intersight_api_reference.py -l | grep -i template

# Correct name is vnic.VnicTemplate
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p

Slow First Execution

Problem: First query takes 10 seconds

Solution: This is normal for the initial YAML parsing. Subsequent queries are instant. For multiple queries, keep the script running in an interactive session.

Multiple OpenAPI Files

Problem:

`1`	`Warning: Multiple spec files found, using: intersight-openapi-v3-1.0.11.yaml`

Solution: Explicitly specify the file:

1
2
3
4
python3 get_intersight_api_reference.py \
  -s /path/to/specific/openapi.yaml \
  -t vnic.VnicTemplate \
  -p

Command Reference

Options Summary

Option	Short	Description
`--type TYPE`	`-t TYPE`	Object type to query
`--properties`	`-p`	Show all properties
`--relationships`	`-r`	Show relationships only
`--output PATH`	`-o PATH`	Export to JSON
`--spec PATH`	`-s PATH`	OpenAPI spec file path
`--list [PREFIX]`	`-l [PREFIX]`	List schemas (filtered)

Common Commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# List all schemas
python3 get_intersight_api_reference.py

# List vnic.* schemas
python3 get_intersight_api_reference.py -l vnic

# Show all properties
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p

# Show relationships only
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -r

# Export to JSON
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p -o output.json

Best Practices

1. Start with Relationships

When exploring a new schema, always check relationships first:

`1`	`python3 get_intersight_api_reference.py -t <ObjectType> -r`

This reveals the dependency graph immediately.

2. Export for Reference

Keep JSON exports of frequently-used schemas:

1
2
mkdir -p api-schemas
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p -o api-schemas/vnic-template.json

3. Validate Before Coding

Before implementing a function, verify:

1
2
3
4
5
# Check schema exists
python3 get_intersight_api_reference.py -t <ObjectType> -p

# Verify all referenced types exist
# (Extract from relationships and check each)

4. Document Assumptions

Add comments referencing the tool output:

1
2
3
# Source: get_intersight_api_reference.py -t vnic.VnicTemplate -r
# FabricEthNetworkGroupPolicy is an array of relationships
# FabricEthNetworkControlPolicy is mandatory (single relationship)

5. Update After SDK Changes

When updating the Intersight PowerShell SDK:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Export current schemas
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p -o before.json

# Update SDK (which includes new OpenAPI spec)

# Export new schemas
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p -o after.json

# Compare
diff -u before.json after.json

Conclusion

The get_intersight_api_reference.py tool transforms the challenge of navigating a massive API specification into a streamlined workflow. By automating inheritance resolution, relationship detection, and property analysis, it enables developers to:

Understand complex object structures in seconds
Validate implementations against the specification
Document API usage patterns
Accelerate development with accurate property information

For PowerShell module development, this tool is invaluable. It bridges the gap between the OpenAPI specification and practical implementation, reducing errors and development time.

Resources

Tool Files

get_intersight_api_reference.py - The Python script
Full documentation in api-reference-tool.md

Official Documentation

Full Tool Documentation

Below is the complete reference documentation for the tool.

Overview

The get_intersight_api_reference.py script extracts structured information from the Intersight OpenAPI v3 specification. This is particularly useful when developing PowerShell functions that interact with the Intersight API.

Usage

Basic Syntax

1
python3 get_intersight_api_reference.py [OPTIONS]

Available Options

Option	Short	Description
`--type TYPE`	`-t TYPE`	Object type to query (e.g., `vnic.VnicTemplate`)
`--properties`	`-p`	Show detailed property information
`--relationships`	`-r`	Show relationship properties only
`--output PATH`	`-o PATH`	Export results to JSON file
`--spec PATH`	`-s PATH`	Path to OpenAPI spec file (auto-detected if not specified)
`--list [PREFIX]`	`-l [PREFIX]`	List available schemas (optionally filtered by prefix)

Examples

1. List All Available Object Types

`1`	`python3 get_intersight_api_reference.py`

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
=== Available Object Types ===

  aaaudit.* (5 schemas)
  aaa.* (15 schemas)
  adapter.* (45 schemas)
  ...
  vnic.* (28 schemas)
  workflow.* (35 schemas)

Total: 5394 schemas

2. List All vnic.* Schemas

`1`	`python3 get_intersight_api_reference.py -l vnic`

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
=== Available Object Types ===

  vnic.*
    - vnic.BaseEthIf
    - vnic.Cdn
    - vnic.EthAdapter
    - vnic.EthAdapterPolicy
    - vnic.EthIf
    - vnic.EthNetworkPolicy
    - vnic.EthQosPolicy
    - vnic.VnicTemplate
    ...

Total: 28 schemas

3. Show All Properties of an Object

`1`	`python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p`

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
=== vnic.VnicTemplate ===

Description:
  The vNIC template consists of the common vNIC configuration...

Inherits from:
  - vnic.BaseEthIf
  - Inline definition

Required Properties:
  - ObjectType
  - ClassId

All Properties:

  Name
    Type: string
    Description: Name of the vNIC template.

  MacPool [REL]
    Type: → macpool.Pool.Relationship
    Description: A reference to a macpoolPool resource.

  FabricEthNetworkGroupPolicy [REL]
    Type: array of fabric.EthNetworkGroupPolicy.Relationship
    Description: An array of relationships to fabricEthNetworkGroupPolicy resources.

  ...

Legend: [REL] = Relationship, [RO] = Read-only

Total Properties: 38
Relationships: 11

4. Show Only Relationship Properties

`1`	`python3 get_intersight_api_reference.py -t vnic.VnicTemplate -r`

Output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
=== vnic.VnicTemplate ===

Relationship Properties:

  EthAdapterPolicy
    Type: vnic.EthAdapterPolicy.Relationship
    Description: A reference to a vnicEthAdapterPolicy resource.

  EthQosPolicy
    Type: vnic.EthQosPolicy.Relationship
    Description: A reference to a vnicEthQosPolicy resource.

  FabricEthNetworkGroupPolicy
    Type: fabric.EthNetworkGroupPolicy.Relationship
    Description: An array of relationships to fabricEthNetworkGroupPolicy resources.

  FabricEthNetworkControlPolicy
    Type: fabric.EthNetworkControlPolicy.Relationship
    Description: A reference to a fabricEthNetworkControlPolicy resource.

  IscsiBootPolicy
    Type: vnic.IscsiBootPolicy.Relationship
    Description: A reference to a vnicIscsiBootPolicy resource.

  MacPool
    Type: macpool.Pool.Relationship
    Description: A reference to a macpoolPool resource.

  Organization
    Type: organization.Organization.Relationship
    Description: A reference to a organizationOrganization resource.

Total Properties: 38
Relationships: 11

5. Export Schema as JSON

1
2
3
4
python3 get_intersight_api_reference.py \
  -t vnic.VnicTemplate \
  -p \
  -o docs/vnic-template-schema.json

JSON Structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "object_type": "vnic.VnicTemplate",
  "description": "The vNIC template consists of...",
  "type": "",
  "required": ["ObjectType", "ClassId"],
  "all_of": ["vnic.BaseEthIf", "Inline definition"],
  "properties": {
    "Name": {
      "name": "Name",
      "type": "string",
      "description": "Name of the vNIC template.",
      "format": null,
      "read_only": false,
      "items": null,
      "ref": null,
      "is_relationship": false,
      "enum": null,
      "default": null
    }
  },
  "relationships": {
    "MacPool": {
      "name": "MacPool",
      "type": null,
      "description": "A reference to a macpoolPool resource.",
      "ref": "macpool.Pool.Relationship",
      "is_relationship": true
    }
  }
}

Use Cases

1. Develop New PowerShell Function

When developing a function like Copy-IntersightVnicTemplate:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Understand available properties
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p

# Identify all relationships
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -r

# Export for documentation
python3 get_intersight_api_reference.py \
  -t vnic.VnicTemplate \
  -p \
  -o docs/api-vnic-template.json

2. Identify Mandatory Properties

1
python3 get_intersight_api_reference.py -t fabric.EthNetworkControlPolicy -p | grep -A 5 "Required Properties"

Output:

1
2
3
Required Properties:
  - ClassId
  - ObjectType

3. Property Types for Validation

1
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p | grep -A 3 "SwitchId"

Output:

1
2
3
4
5
  SwitchId
    Type: string
    Description: The fabric port to which the vNICs will be associated.
    Enum: None, A, B
    Default: None

4. Understand Inheritance Hierarchy

1
python3 get_intersight_api_reference.py -t vnic.VnicTemplate -p | grep -A 3 "Inherits from"

Output:

1
2
3
Inherits from:
  - vnic.BaseEthIf
  - Inline definition

Important Object Types

vNIC and LAN Connectivity

Object Type	Description	Used By
`vnic.VnicTemplate`	vNIC Template	Cloned by `Copy-IntersightVnicTemplate`
`vnic.EthIf`	Ethernet Interface	Derived from vNIC Template
`vnic.LanConnectivityPolicy`	LAN Connectivity Policy	Container for EthIfs
`fabric.EthNetworkGroupPolicy`	VLAN Groups	Defines allowed VLANs
`fabric.EthNetworkControlPolicy`	Network Control	CDP, LLDP, MAC learning

Policies

Object Type	Description
`vnic.EthAdapterPolicy`	Adapter settings
`vnic.EthQosPolicy`	QoS settings
`macpool.Pool`	MAC address pools
`vnic.IscsiBootPolicy`	iSCSI boot configuration

Queries

1
2
3
4
5
6
7
8
# All vnic.* types
python3 get_intersight_api_reference.py -l vnic

# All fabric.* types
python3 get_intersight_api_reference.py -l fabric

# All macpool.* types
python3 get_intersight_api_reference.py -l macpool

Property Markers

The tool uses the following markers in its output:

[REL] - Relationship: Property references another object
[RO] - Read-Only: Property cannot be modified
→ - Reference: Shows the referenced type

Integration in Development Workflow

Explore Schema: Understand available properties and relationships
Identify Mandatory Properties: Ensure all required fields are set
Understand Relationships: Determine which MoMoRefs need to be created
Validate Enum Values: Use enum information for parameter validation
Generate Documentation: Export as JSON for further processing

Technical Details

Inheritance Resolution

The script automatically resolves allOf references and merges properties from parent schemas. Example:

1
2
3
4
5
6
7
vnic.VnicTemplate
  ↓ allOf
  ├─ vnic.BaseEthIf
  │  ↓ allOf
  │  ├─ policy.AbstractPolicy
  │  └─ mo.BaseMo
  └─ Inline definition

All properties are combined and displayed.

Relationship Detection

Properties are detected as relationships when:

The type ends with Relationship (e.g., vnic.EthAdapterPolicy.Relationship)
The type is MoMoRef or mo.MoRef
It’s an array of relationships

Performance

First execution: ~5-10 seconds (YAML parsing)
Subsequent queries: Immediate (if already loaded)
Large file: 575,110 lines, ~180 MB

Troubleshooting

“Schema not found” Error

1
2
# Check available schemas
python3 get_intersight_api_reference.py -l | grep -i <search-term>

OpenAPI Spec Not Found

1
2
3
4
5
# Explicitly specify path
python3 get_intersight_api_reference.py \
  -s /path/to/intersight-openapi-*.yaml \
  -t vnic.VnicTemplate \
  -p

YAML Parsing Slow

The first execution takes longer because the entire YAML document must be loaded. This is normal for a ~180 MB specification.

Published: February 7, 2026 Last Updated: February 7, 2026

Introduction#

The Challenge#

The Solution: get_intersight_api_reference.py#

Key Features#

Installation and Setup#

Prerequisites#

Download the OpenAPI Specification#

Verify the Setup#

Basic Usage#

List All Available Schemas#

Filter Schemas by Module#

Explore a Specific Schema#

Focus on Relationships#

Export for Processing#

Real-World Development Workflow#

Scenario: Clone a vNIC Template#

Step 1: Understand the Schema#

Step 2: Identify Mandatory Relationships#

Step 3: Understand Network Group Policy#

Step 4: Check Property Types#

Step 5: Implement in PowerShell#

Advanced Use Cases#

1. Validate Parameter Sets#

2. Document API Changes#

3. Generate Documentation#

4. Bulk Analysis#

Technical Deep Dive#

Inheritance Resolution#

Relationship Detection Algorithm#

Performance Considerations#

Property Markers Explained#

Integration with CI/CD#

Pre-Commit Hook#

Documentation Generation#

Comparison with Alternatives#

vs. Manual YAML Search#

vs. Web Documentation#

vs. IDE Schema Hints#

Common Patterns and Idioms#

Pattern 1: Single Relationship Property#

Pattern 2: Array of Relationships#

Pattern 3: Enum Validation#

Pattern 4: Conditional Mandatory Properties#

Troubleshooting#

Schema Not Found#

Slow First Execution#

Multiple OpenAPI Files#

Command Reference#

Options Summary#

Common Commands#

Best Practices#

1. Start with Relationships#

2. Export for Reference#

3. Validate Before Coding#

4. Document Assumptions#

5. Update After SDK Changes#

Conclusion#

Resources#

Tool Files#

Official Documentation#

Full Tool Documentation#

Overview#

Usage#

Basic Syntax#

Available Options#

Examples#

1. List All Available Object Types#

2. List All vnic.* Schemas#

3. Show All Properties of an Object#

4. Show Only Relationship Properties#

5. Export Schema as JSON#

Use Cases#

1. Develop New PowerShell Function#

2. Identify Mandatory Properties#

3. Property Types for Validation#

4. Understand Inheritance Hierarchy#

Important Object Types#

vNIC and LAN Connectivity#

Policies#

Queries#

Introduction

The Challenge

The Solution: `get_intersight_api_reference.py`

Key Features

Installation and Setup

Prerequisites

Download the OpenAPI Specification

Verify the Setup

Basic Usage

List All Available Schemas

Filter Schemas by Module

Explore a Specific Schema

Focus on Relationships

Export for Processing

Real-World Development Workflow

Scenario: Clone a vNIC Template

Step 1: Understand the Schema

Step 2: Identify Mandatory Relationships

Step 3: Understand Network Group Policy

Step 4: Check Property Types

Step 5: Implement in PowerShell

Advanced Use Cases

1. Validate Parameter Sets

2. Document API Changes

3. Generate Documentation

4. Bulk Analysis

Technical Deep Dive

Inheritance Resolution

Relationship Detection Algorithm

Performance Considerations

Property Markers Explained

Integration with CI/CD

Pre-Commit Hook

Documentation Generation

Comparison with Alternatives

vs. Manual YAML Search

vs. Web Documentation

vs. IDE Schema Hints

Common Patterns and Idioms

Pattern 1: Single Relationship Property

Pattern 2: Array of Relationships

Pattern 3: Enum Validation

Pattern 4: Conditional Mandatory Properties

Troubleshooting

Schema Not Found

Slow First Execution

Multiple OpenAPI Files

Command Reference

Options Summary

Common Commands

Best Practices

1. Start with Relationships

2. Export for Reference

3. Validate Before Coding

4. Document Assumptions

5. Update After SDK Changes

Conclusion

Resources

Tool Files

Official Documentation

Full Tool Documentation

Overview

Usage

Basic Syntax

Available Options

Examples

1. List All Available Object Types

2. List All vnic.* Schemas

3. Show All Properties of an Object

4. Show Only Relationship Properties

5. Export Schema as JSON

Use Cases

1. Develop New PowerShell Function

2. Identify Mandatory Properties

3. Property Types for Validation

4. Understand Inheritance Hierarchy

Important Object Types

vNIC and LAN Connectivity

Policies

Queries