Introduction

The Kubernetes REST API is the control surface behind kubectl, controllers, and most cluster automation. If you can authenticate to the API server and understand the resource paths, you can list, inspect, create, and update Kubernetes objects directly over HTTP.

Core API Structure

Kubernetes exposes two main path families.

• '/api for core resources such as pods, services, namespaces, and config maps'
• '/apis for grouped APIs such as deployments in apps/v1'

For example, listing pods in the default namespace uses the core API path:

curl -s http://127.0.0.1:8001/api/v1/namespaces/default/pods

A deployment list uses the grouped API path:

curl -s http://127.0.0.1:8001/apis/apps/v1/namespaces/default/deployments

The Easiest Way to Explore: kubectl proxy

Direct API-server authentication can be noisy while you are learning. A practical starting point is kubectl proxy, which opens a local HTTP endpoint and forwards authenticated traffic using your current kubeconfig.

kubectl proxy --port=8001

After that, basic GET requests become easy:

curl -s http://127.0.0.1:8001/api/v1/namespaces/default/pods | jq '.items[].metadata.name'

That is useful for debugging, scripting, and understanding what kubectl commands map to under the hood.

Reading and Writing Resources

The API is resource-oriented. A GET reads objects, a POST creates one, a PUT replaces one, and a PATCH updates part of one.

Here is a simple create request for a config map through the proxy:

1cat <<'JSON' >/tmp/configmap.json
2{
3  "apiVersion": "v1",
4  "kind": "ConfigMap",
5  "metadata": {
6    "name": "app-config",
7    "namespace": "default"
8  },
9  "data": {
10    "MODE": "development"
11  }
12}
13JSON
14
15curl -s \
16  -H 'Content-Type: application/json' \
17  -X POST \
18  --data-binary @/tmp/configmap.json \
19  http://127.0.0.1:8001/api/v1/namespaces/default/configmaps

The server validates the object and stores it in etcd through the normal Kubernetes control-plane path.

Authentication Outside kubectl proxy

In production integrations, clients usually authenticate with a kubeconfig credential, a service-account token, or an external identity provider. Inside a pod, Kubernetes mounts service-account credentials by default unless that behavior is disabled.

A direct in-cluster call often looks like this:

1TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
2CACERT=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
3API=https://kubernetes.default.svc
4
5curl --cacert "$CACERT" \
6  -H "Authorization: Bearer $TOKEN" \
7  "$API/api/v1/namespaces/default/pods"

That pattern is common in operators, sidecars, and diagnostic tools running inside the cluster.

Namespaces, Versions, and Discovery

Resource URLs include both version and scope. Some resources are namespaced, such as pods and secrets. Others are cluster-scoped, such as nodes and namespaces.

You can discover what the server supports through endpoints such as:

curl -s http://127.0.0.1:8001/api
curl -s http://127.0.0.1:8001/apis

That is useful because Kubernetes evolves over time, and not every cluster exposes the same CRDs or API groups.

Watch Requests and Automation

The REST API also supports watch semantics so clients can follow resource changes over time instead of polling repeatedly.

curl -s 'http://127.0.0.1:8001/api/v1/namespaces/default/pods?watch=1'

Controllers and operators rely heavily on this model. They read the current state, watch for changes, and reconcile toward the desired state.

Common Pitfalls

A common mistake is calling the wrong path family, such as using /api for deployments instead of /apis/apps/v1. Another is forgetting namespace scope and then wondering why a resource is not found. Developers also often test through kubectl proxy successfully but then omit authentication and TLS details when switching to direct API-server calls. Finally, writing objects with outdated API versions can fail even if an old example looked correct on a different cluster.

Summary

• The Kubernetes REST API is the HTTP interface behind most cluster operations.
• Use /api for core resources and /apis for grouped resources.
• 'kubectl proxy is the easiest way to explore the API locally.'
• Direct calls need proper authentication, TLS, and the correct namespace scope.
• Discovery endpoints help you confirm supported API groups and versions before automating against them.