Document PartialObjectMetadata accept param (#51994)

* Document PartialObjectMetadata accept param

* Apply feedback

* Apply suggestions from sftim

Co-authored-by: Tim Bannister <[email protected]>

---------

Co-authored-by: Tim Bannister <[email protected]>

Author: jpbetz

content/en/docs/reference/using-api/api-concepts.md

@@ -191,6 +191,9 @@ For example:
    }
    ```
 
+You can also request [table](#table-fetches) and [metadata-only](#metadata-only-fetches)
+representations of this encoding.
+
 ### YAML resource encoding {#yaml-encoding}
 
 Kubernetes also supports the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html)
@@ -233,6 +236,9 @@ For example:
      …
    ```
 
+You can also request [table](#table-fetches) and [metadata-only](#metadata-only-fetches)
+representations of this encoding.
+
 ### Kubernetes Protobuf encoding {#protobuf-encoding}
 
 Kubernetes uses an envelope wrapper to encode [Protobuf](https://protobuf.dev/) responses.
@@ -322,6 +328,9 @@ to alter the serialization format in an incompatible way and will do so by chang
 the prefix.
 {{< /note >}}
 
+You can also request [table](#table-fetches) and [metadata-only](#metadata-only-fetches)
+representations of this encoding.
+
 #### Compatibility with Kubernetes Protobuf {#protobuf-encoding-compatibility}
 
 Not all API resource types support Kubernetes' Protobuf encoding; specifically, Protobuf isn't
@@ -367,6 +376,9 @@ In addition to the existing `application/apply-patch+yaml` media type for YAML-e
 is no supported CBOR equivalent for `application/json-patch+json` or `application/merge-patch+json`,
 or `application/strategic-merge-patch+json`.
 
+You can also request [table](#table-fetches) and [metadata-only](#metadata-only-fetches)
+representations of this encoding.
+
 ## Efficient detection of changes
 
 The Kubernetes API allows clients to make an initial request for an object or a
@@ -765,7 +777,7 @@ collections that might be of different kinds of object. Avoid depending on
 `kind: List` in automation or other code.
 {{< /note >}}
 
-## Receiving resources as Tables
+## Table fetches
 
 When you run `kubectl get`, the default output format is a simple tabular
 representation of one or more instances of a particular resource type. In the past,
@@ -845,6 +857,102 @@ extensions, you should make requests that specify multiple content types in the
 Accept: application/json;as=Table;g=meta.k8s.io;v=v1, application/json
 ```
 
+If the client indicates it only accepts `...;as=Table;g=meta.k8s.io;v=v1`, servers
+that don't support table responses will return a 406 error code.
+
+If falling back to full objects in that case is desired, clients can add `,application/json`
+(or any other supported encoding) to their Accept header, and handle either
+table or full objects in the response:
+
+```http
+Accept: application/json;as=Table;g=meta.k8s.io;v=v1,application/json`
+```
+
+For more information on content type negotiation, see the
+[MDN Content Negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation).
+
+## Metadata-only fetches
+
+To request partial object metadata, you can request metadata only responses in the `Accept`
+header. The Kubernetes API implements a variation on HTTP content type negotiation.
+As a client, you can provide an `Accept` header with the desired media type,
+along with parameters that indicate you want only metadata.
+For example: `Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1`
+for JSON.
+
+For example, to list all of the pods in a cluster, across all namespaces, but returning only the metadata for each pod:
+
+```http
+GET /api/v1/pods
+Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1
+---
+200 OK
+Content-Type: application/json
+
+{
+    "kind": "PartialObjectMetadataList",
+    "apiVersion": "meta.k8s.io/v1",
+    "metadata": {
+        "resourceVersion": "...",
+    },
+    "items": [
+        {
+            "apiVersion": "meta.k8s.io/v1",
+            "kind": "PartialObjectMetadata",
+            "metadata": {
+                "name": "pod-1",
+                ...
+            }
+        },
+        {
+            "apiVersion": "meta.k8s.io/v1",
+            "kind": "PartialObjectMetadata",
+            "metadata": {
+                "name": "pod-2",
+                ...
+            }
+        }
+    ]
+}
+```
+
+For a request for a collection, the API server returns a PartialObjectMetadataList.
+For a request for a single object, the API server returns a PartialObjectMetadata
+representation of the
+object. In both cases, the returned objects only contain the `metadata` field.
+The `spec` and `status` fields are omitted.
+
+This feature is useful for clients that only need to check for the existence of
+an object, or that only need to read its metadata. It can significantly reduce
+the size of the response from the API server.
+
+You can request a metadata-only fetch for all available media types (JSON, YAML, CBOR and Kubernetes Protobuf).
+For Protobuf, the
+`Accept` header would be
+`application/vnd.kubernetes.protobuf;as=PartialObjectMetadata;g=meta.k8s.io;v=v1`.
+
+The Kubernetes API server supports partial fetching for nearly all of its built-in APIs.
+However, you can use Kubernetes to access other API servers via the
+{{< glossary_tooltip text="aggregation layer" term_id="aggregation-layer" >}}, and those
+APIs may not support partial fetches.
+
+If a client uses the `Accept` header to **only** request a response `...;as=PartialObjectMetadata;g=meta.k8s.io;v=v1`,
+and accesses an API that doesn't support partial responses, Kubernetes responds
+with a 406 HTTP error.
+
+
+If falling back to full objects in that case is desired, clients can add `,application/json`
+(or any other supported encoding) to their Accept header, and handle either
+PartialObjectMetadata or full objects in the response. It's a good idea to specify
+that a partial response is preferred, using the `q` (_quality_) parameter. For example:
+
+```http
+Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1, application/json;q=0.9
+```
+
+For more information on content type negotiation, see the
+[MDN Content Negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation).
+
 ## Resource deletion
 
 When you **delete** a resource this takes place in two phases.