Kubernetes API Definition

Kubernetes API Definition is the precise characterization of the Kubernetes API as a versioned, resource-oriented, RESTful interface through which every read and write to a cluster's state occurs, exposed exclusively by the API server and governed by a uniform set of conventions applied consistently across both built-in and user-defined resource types. Formally, the API is not merely an implementation detail of the API server; it is the contract that defines what a Kubernetes cluster is capable of expressing, since no object, built-in or custom, can exist within a cluster except as an instance of some resource defined by this API.

Formal Structure of the API

Resource-Oriented Design

The API is organized around resources, nouns representing a category of object, such as Pod or Deployment, each exposed at a predictable URL path and manipulated through standard HTTP verbs: GET to retrieve, POST to create, PUT or PATCH to update, and DELETE to remove.

GET  /api/v1/namespaces/codartium-team/pods
POST /apis/apps/v1/namespaces/codartium-team/deployments

Groups, Versions, and Kinds

Every resource in the API is uniquely identified by the triple of API group, version, and kind, commonly abbreviated GVK. The core group, addressed without an explicit group name, contains foundational resources; named groups, such as apps or batch, contain resources organized by functional area, and each group independently manages its own set of served versions.

Defining Conventions

Uniform Object Structure

Every resource served by the API, regardless of group or kind, follows the same structural convention: an apiVersion and kind identifying its type, a metadata block carrying identity and labeling information common to all resources, and a spec describing desired state, typically paired with a status describing observed state.

The Watch Contract

The API formally guarantees a watch interface for collections of resources, through which clients receive an initial snapshot followed by a continuous stream of ADDED, MODIFIED, and DELETED events, a defining capability that distinguishes the Kubernetes API from a conventional CRUD-only REST API and underlies the entire controller and reconciliation model built on top of it.

kubectl get pods --watch -n codartium-team

Optimistic Concurrency

Every object carries a resourceVersion, and the API formally rejects update requests referencing a stale resourceVersion, requiring clients to re-read and reapply their change, a defining mechanism that prevents lost updates under concurrent modification without requiring the API to expose any locking primitive.

Extensibility as Part of the Definition

CRDs Extend, Not Replace, the API

A Custom Resource Definition does not create a parallel system; it registers a new kind that is served through the exact same API conventions, the exact same URL structure, the exact same watch and versioning guarantees, as any built-in resource. This is a defining property of the API's design: extension does not require a separate protocol.

API Aggregation

Where an aggregated API server serves a resource type directly, the primary API server transparently proxies requests to it, so that from a client's perspective, the API remains a single, coherent surface regardless of how many independent components are actually implementing parts of it behind the scenes.

Versioning as a Formal Guarantee

Stability Tiers

The API formally defines three stability tiers for any given version of a resource: alpha, offering no compatibility guarantee and disabled by default; beta, enabled by default but still subject to schema changes; and stable (v1 and beyond), bound by a formal deprecation policy requiring advance notice before any breaking change or removal.

apps/v1        # stable
batch/v1       # stable
policy/v1beta1 # beta (illustrative)

Multi-Version Serving and Conversion

A single kind can be served simultaneously at multiple versions, with the API server performing conversion between them and persisting a single canonical storage version, a formally specified behavior that allows clients built against different versions to interoperate against the same underlying objects.

The API as the Cluster's Only Interface

No Bypass Path

By definition, there is no supported path for modifying cluster state other than through the API; even components that appear to operate "beneath" it, such as the scheduler binding a Pod to a node, do so by issuing ordinary API write requests rather than through any privileged, out-of-band channel.

kubectl api-resources
kubectl explain pod.spec --recursive

Implication for Tooling

Because every tool, kubectl, client libraries, controllers, third-party operators, interacts with the cluster exclusively through this single, uniformly structured API, any tool capable of speaking the API's conventions can operate over any resource type the cluster serves, built-in or custom, without needing resource-specific integration code.