5.12 Kubernetes API Request Model

Kubernetes API Request Model is the set of HTTP verbs, URL path conventions, and content negotiation rules that clients use to interact with resources exposed by the API server, defining how creates, reads, updates, deletes, and watches are structured as concrete HTTP requests against a REST-like but Kubernetes-specific set of semantics layered on top of standard HTTP methods.

URL Path Structure

Core Group Paths

Requests against the core, unnamed API group use the path prefix /api/v1/, followed by an optional namespace segment for namespaced resources, then the resource name and optionally a specific object name, such as /api/v1/namespaces/default/pods/my-pod.

Named Group Paths

Requests against named API groups use the prefix /apis/<group>/<version>/, following the same namespace-then-resource-then-name pattern, such as /apis/apps/v1/namespaces/default/deployments/my-deployment, keeping named groups structurally consistent with the core group aside from the additional group segment.

Subresource Paths

Subresource operations append the subresource name as an additional path segment after the object name, such as /api/v1/namespaces/default/pods/my-pod/status or /apis/apps/v1/namespaces/default/deployments/my-deployment/scale, addressing the subresource as its own distinct endpoint.

Standard Verbs and Their HTTP Mapping

Create

Creating an object is performed with an HTTP POST to a resource's collection endpoint, with the request body containing the full object manifest; the API server assigns system-managed fields such as uid and resourceVersion and returns the persisted object, including these newly populated fields, in the response.

Get and List

Retrieving a single object uses HTTP GET against the object's specific path, while retrieving a collection uses HTTP GET against the resource's collection path, optionally filtered by label or field selectors passed as query parameters, returning a List-kind object wrapping the matching items.

Update and Patch

A full update uses HTTP PUT, requiring the client to submit the complete object body including an up-to-date resourceVersion for optimistic concurrency checking, while a partial update uses HTTP PATCH, supporting several patch formats including JSON Patch, JSON Merge Patch, and the Kubernetes-specific strategic merge patch and server-side apply formats.

Delete

Deleting an object uses HTTP DELETE, optionally carrying a request body specifying deletion options such as propagationPolicy or gracePeriodSeconds, which govern cascading deletion behavior and how long the object lingers before being finally removed.

Watch as a Long-Lived Request

Establishing a Watch

Adding a watch=true query parameter to a list request transforms it into a long-lived connection over which the API server streams a sequence of watch events, rather than returning a single, static response, allowing a client to observe changes to a resource collection as they happen.

Watch Event Structure

Each streamed event carries a type, ADDED, MODIFIED, DELETED, or BOOKMARK, and the full object as it exists after that change, giving the watching client enough information to maintain an accurate, continuously updated local representation of the resource collection without repeatedly re-listing it.

Resuming Watches with resourceVersion

A client can resume a previously interrupted watch from a specific point by supplying the last known resourceVersion as a starting point, and the API server, backed by etcd's revisioned storage, can replay events from that point forward, or signal that the requested version is too old and a fresh list is required.

Field and Label Selectors on Requests

Label Selector Query Parameter

List and watch requests accept a labelSelector query parameter, allowing the server to filter the requested collection to only objects whose labels satisfy the given selector expression before the response is even constructed, reducing both response size and unnecessary data transfer.

Field Selector Query Parameter

A more limited fieldSelector query parameter allows filtering based on specific, indexed fields of an object, such as metadata.name or status.phase, though the set of fields supported for field selection is narrower than the full breadth of fields available for label-based filtering.

Content Negotiation

Supported Media Types

The API server supports multiple serialization formats, including JSON and, more efficiently, Protocol Buffers, negotiated through standard HTTP Accept and Content-Type headers, with Protocol Buffers commonly used by internal cluster components for reduced payload size and faster parsing compared to JSON.

Impact on Client Tooling

Most user-facing tools, including kubectl, default to JSON for readability and broad compatibility, while performance-sensitive internal clients, such as controllers built with client-go, typically negotiate Protocol Buffers to minimize serialization overhead across the very large volume of requests a busy control plane processes.