Kubernetes API Concepts [page]deterministic

reference

The Kubernetes API is a resource-based (RESTful) programmatic interface provided via HTTP. It supports retrieving, creating, updating, and deleting primary resources via the standard HTTP verbs (POST, PUT, PATCH, DELETE, GET).

For some resources, the API includes additional subresources that allow fine-grained authorization (such as separate views for Pod details and log retrievals), and can accept and serve those resources in different representations for convenience or efficiency.

Kubernetes supports efficient change notifications on resources via _watches_: [definition:watch] Kubernetes also provides consistent list operations so that API clients can effectively cache, track, and synchronize the state of resources.

You can view the [API reference](/docs/reference/kubernetes-api/) online, or read on to learn about the API in general.

## Kubernetes API terminology {#standard-api-terminology}

Kubernetes generally leverages common RESTful terminology to describe the API concepts:

* A *resource type* is the name used in the URL (`pods`, `namespaces`, `services`) * All resource types have a concrete representation (their object schema) which is called a *kind* * A list of instances of a resource type is known as a *collection* * A single instance of a resource type is called a *resource*, and also usually represents an *object* * For some resource types, the API includes one or more *sub-resources*, which are represented as URI paths below the resource

Most Kubernetes API resource types are [objects](#gloss:object) – they represent a concrete instance of a concept on the cluster, like a pod or namespace. A smaller number of API resource types are *virtual* in that they often represent operations on objects, rather than objects, such as a permission check (use a POST with a JSON-encoded body of `SubjectAccessReview` to the `subjectaccessreviews` resource), or the `eviction` sub-resource of a Pod (used to trigger [API-initiated eviction](/docs/concepts/scheduling-eviction/api-eviction/)).

### Object names

All objects you can create via the API have a unique object [name](#gloss:name) to allow idempotent creation and retrieval, except that virtual resource types may not have unique names if they are not retrievable, or do not rely on idempotency.

Within a [namespace](#gloss:namespace), an object's unique identity is defined by the tuple of its API Group, Resource, Namespace, and Name.

* Cross-Group: You can have two objects with the same name if they belong to different API Groups (for example, `apps` vs. `example.com`). * Cross-Version: Different API Versions (such as `v1` and `v1beta1`) of the same Group and Resource represent the same underlying data. Creating an object with the same name in a different version of the same group results in a name clash, as they share the same identity in storage.

Some objects are not namespaced (for example: Nodes), and so their names must be unique across the whole cluster.

### API verbs

Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH, and DELETE. Kubernetes also uses its own verbs, which are often written in lowercase to distinguish them from HTTP verbs.

Kubernetes uses the term list to describe the action of returning a [collection](#collections) of resources, to distinguish it from retrieving a single resource which is usually called a get. If you sent an HTTP GET request with the `?watch` query parameter, Kubernetes calls this a watch and not a get (see [Efficient detection of changes](#efficient-detection-of-changes) for more details).

For PUT requests, Kubernetes internally classifies these as either create or update based on the state of the existing object. An update is different from a patch; the HTTP verb for a patch is PATCH.

## Resource URIs

All resource types are either scoped by the cluster (`/apis/GROUP/VERSION/*`) or to a namespace (`/apis/GROUP/VERSION/namespa …(trimmed)