Course contentsShow
← Cloud and Infrastructure
Lesson 1127 of 2,98922. Kubernetes ArchitectureFree lesson

API Discovery and OpenAPI Schema

Explore how clients discover available APIs and retrieve schema definitions for validation.

API Discovery and OpenAPI Schema

What you'll learn: How clients find out what's available in the Kubernetes API and validate their requests before sending them.

When you interact with a Kubernetes cluster, you need to know what resources exist, what versions they support, and how to structure your requests correctly. API discovery is the process by which clients (like kubectl or custom applications) learn what the cluster offers without hardcoding this knowledge.

How Discovery Works

Think of API discovery like walking into a library with a computerized catalog. Instead of memorizing every book, you query the catalog to see what's available, where it is, and how it's organized.

Kubernetes exposes discovery endpoints at the API server that clients can query:

  • /api and /apis list available API groups
  • Each group endpoint reveals supported versions
  • Version endpoints list available resources (Pods, Services, etc.)

This dynamic discovery means your client tools work across different Kubernetes versions and with custom resources without needing updates.

OpenAPI Schema: The Validation Blueprint

Once you know what resources exist, you need to know their exact structure. The OpenAPI schema (formerly Swagger) provides a machine-readable specification describing:

  • Required and optional fields
  • Field data types (string, integer, object)
  • Valid values and constraints
  • Nested object structures

The API server exposes this schema at /openapi/v2 or /openapi/v3. When you run kubectl explain pod.spec.containers, you're querying this schema. It enables client-side validation, preventing malformed requests from reaching the server and providing helpful error messages.

Key Takeaway: API discovery lets clients dynamically learn what resources a cluster supports, while the OpenAPI schema provides the exact specification needed to construct valid requests—together they enable flexible, self-documenting API interactions without hardcoded assumptions.