Kubernetes API Usage Guide
Documentation Design
In the Kubernetes APIs documentation, we've taken a deliberate approach to focus on the schema definitions of resources rather than listing the specific API paths, parameters, and request methods for each resource. This design choice is based on the following considerations:
-
Consistency: All Kubernetes API resources follow the same RESTful API pattern, making it redundant to repeat the same calling patterns for each resource.
-
Readability: Documenting the complete API details for every resource would result in lengthy, repetitive documentation that would be harder to navigate and digest.
-
Focus on what matters: For most users, understanding the resource schema (what fields are available and what they mean) is more important than the HTTP mechanics of the API calls.
-
Compatibility with tools: Most users interact with these APIs through Kubernetes clients (kubectl, client-go, etc.) rather than direct HTTP calls, making the HTTP details less relevant for day-to-day operations.
While our Kubernetes APIs documentation focuses on the schema definitions of resources, this guide complements it by explaining the general usage patterns and calling conventions for Kubernetes APIs. Here you will learn how to structure API requests, understand common HTTP methods, and see the standard URL paths for different operations - information that applies universally to all Kubernetes resources.
Standard Kubernetes API Call Patterns
This section provides only a basic introduction to Kubernetes APIs usage patterns. For a more comprehensive and detailed explanation of Kubernetes APIs, please refer to the official Kubernetes API Concepts documentation.
All Kubernetes API resources support a standard set of operations that follow RESTful conventions. Below are the common API call patterns that apply to all resources listed in our Kubernetes APIs documentation:
Resource Collections
For resource collections (like Pods, Deployments, etc.):
| Operation | HTTP Method | Path | Description |
|---|---|---|---|
| List all resources | GET | /apis/{group}/{version}/namespaces/{namespace}/{resource} | Returns a list of resources in the specified namespace |
| List all resources (cluster-wide) | GET | /apis/{group}/{version}/{resource} | Returns a list of resources across all namespaces (for resources that support this) |
| Create a resource | POST | /apis/{group}/{version}/namespaces/{namespace}/{resource} | Creates a new resource in the specified namespace |
| Create a resource (cluster-wide) | POST | /apis/{group}/{version}/{resource} | Creates a new cluster-scoped resource (for resources that support this) |
Individual Resources
For individual resource instances:
| Operation | HTTP Method | Path | Description |
|---|---|---|---|
| Get a resource | GET | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Returns details of a specific resource |
| Get a resource (cluster-wide) | GET | /apis/{group}/{version}/{resource}/{name} | Returns details of a specific cluster-scoped resource |
| Update a resource | PUT | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Replaces the entire resource with the provided definition |
| Update a resource (cluster-wide) | PUT | /apis/{group}/{version}/{resource}/{name} | Replaces the entire cluster-scoped resource with the provided definition |
| Patch a resource | PATCH | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Updates specific fields of the resource |
| Patch a resource (cluster-wide) | PATCH | /apis/{group}/{version}/{resource}/{name} | Updates specific fields of the cluster-scoped resource |
| Delete a resource | DELETE | /apis/{group}/{version}/namespaces/{namespace}/{resource}/{name} | Deletes the specified resource |
| Delete a resource (cluster-wide) | DELETE | /apis/{group}/{version}/{resource}/{name} | Deletes the specified cluster-scoped resource |
Core API Group
For resources in the core API group (v1), the paths are slightly different:
| Operation | HTTP Method | Path | Description |
|---|---|---|---|
| List all resources | GET | /api/v1/namespaces/{namespace}/{resource} | Returns a list of core resources in the specified namespace |
| Get a resource | GET | /api/v1/namespaces/{namespace}/{resource}/{name} | Returns details of a specific core resource |
Common Query Parameters
Kubernetes APIs support several common query parameters that can be added to the request URL:
| Parameter | Description | Example |
|---|---|---|
pretty=true | Returns the response in a more human-readable format | /api/v1/namespaces/default/pods?pretty=true |
labelSelector | Filters resources based on labels | /api/v1/namespaces/default/pods?labelSelector=app=nginx |
fieldSelector | Filters resources based on field values | /api/v1/namespaces/default/pods?fieldSelector=status.phase=Running |
watch=true | Starts a watch connection for changes | /api/v1/namespaces/default/pods?watch=true |
resourceVersion | Specifies from which version to start watching | /api/v1/namespaces/default/pods?watch=true&resourceVersion=12345 |
limit | Limits the number of results returned | /api/v1/namespaces/default/pods?limit=50 |
continue | Token for continuing a previous list request | /api/v1/namespaces/default/pods?continue=eyJ2IjoibWV0Y... |
Conclusion
By following the standard Kubernetes API patterns described in this document, you can interact with any of the resources documented in our Kubernetes APIs section. The schemas provided in the API documentation tell you what data you can send and receive, while this guide explains how to structure your API requests.
For detailed information about specific resource schemas, refer to the Kubernetes APIs section.