Clean up using-api/api-concepts.md

Author: windsonsea

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

@@ -68,11 +68,11 @@ Almost all object resource types support the standard HTTP verbs - GET, POST, PU
 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 returning a [collection](#collections) of
-resources to distinguish from retrieving a single resource which is usually called
+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).
+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
@@ -335,17 +335,16 @@ Accept: application/vnd.kubernetes.protobuf, application/json
 
 {{< feature-state feature_gate_name="CBORServingAndStorage" >}}
 
-With the `CBORServingAndStorage` [feature
-gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled, request and response
-bodies for all built-in resource types and all resources defined by a {{< glossary_tooltip
-term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} may be encoded to the
-[CBOR](https://www.rfc-editor.org/rfc/rfc8949) binary data format. CBOR is also supported at the {{<
-glossary_tooltip text="aggregation layer" term_id="aggregation-layer" >}} if it is enabled in
+With the `CBORServingAndStorage` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+enabled, request and response bodies for all built-in resource types and all resources defined by a
+{{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} may be encoded to the
+[CBOR](https://www.rfc-editor.org/rfc/rfc8949) binary data format. CBOR is also supported at the
+{{< glossary_tooltip text="aggregation layer" term_id="aggregation-layer" >}} if it is enabled in
 individual aggregated API servers.
 
 Clients should indicate the IANA media type `application/cbor` in the `Content-Type` HTTP request
-header when the request body contains a single CBOR [encoded data
-item](https://www.rfc-editor.org/rfc/rfc8949.html#section-1.2-4.2), and in the `Accept` HTTP request
+header when the request body contains a single CBOR
+[encoded data item](https://www.rfc-editor.org/rfc/rfc8949.html#section-1.2-4.2), and in the `Accept` HTTP request
 header when prepared to accept a CBOR encoded data item in the response. API servers will use
 `application/cbor` in the `Content-Type` HTTP response header when the response body contains a
 CBOR-encoded object.
@@ -355,8 +354,8 @@ CBOR, the response body will be a [CBOR Sequence](https://www.rfc-editor.org/rfc
 `Content-Type` HTTP response header will use the IANA media type `application/cbor-seq`. Each entry
 of the sequence (if any) is a single CBOR-encoded watch event.
 
-In addition to the existing `application/apply-patch+yaml` media type for YAML-encoded [server-side
-apply configurations](#patch-and-apply), API servers that enable CBOR will accept the
+In addition to the existing `application/apply-patch+yaml` media type for YAML-encoded
+[server-side apply configurations](#patch-and-apply), API servers that enable CBOR will accept the
 `application/apply-patch+cbor` media type for CBOR-encoded server-side apply configurations. There
 is no supported CBOR equivalent for `application/json-patch+json` or `application/merge-patch+json`,
 or `application/strategic-merge-patch+json`.
@@ -388,7 +387,7 @@ For example:
 
 1. List all of the pods in a given namespace.
 
-   ```
+   ```http
    GET /api/v1/namespaces/test/pods
    ---
    200 OK
@@ -407,7 +406,7 @@ For example:
    _test_ namespace. Each change notification is a JSON document. The HTTP response body
    (served as `application/json`) consists a series of JSON documents.
 
-   ```
+   ```http
    GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
    ---
    200 OK
@@ -444,7 +443,7 @@ to a given `resourceVersion` the client is requesting have already been sent. Th
 document representing the `BOOKMARK` event is of the type requested by the request,
 but only includes a `.metadata.resourceVersion` field. For example:
 
-```
+```http
 GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
 ---
 200 OK
@@ -474,7 +473,7 @@ the API server will send any `BOOKMARK` event even when requested.
 On large clusters, retrieving the collection of some resource types may result in
 a significant increase of resource usage (primarily RAM) on the control plane.
 To alleviate the impact and simplify the user experience of the **list** + **watch**
-pattern, Kubernetes v1.32 promotes to beta the feature that allows requesting the initial state 
+pattern, Kubernetes v1.32 promotes to beta the feature that allows requesting the initial state
 (previously requested via the **list** request) as part of the **watch** request.
 
 On the client-side the initial state can be requested by specifying `sendInitialEvents=true` as query string parameter
@@ -500,7 +499,7 @@ is 10245 and there are two pods: `foo` and `bar`. Then sending the following req
 _consistent read_ by setting empty resource version using `resourceVersion=`) could result
 in the following sequence of events:
 
-```
+```http
 GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan
 ---
 200 OK
@@ -541,7 +540,7 @@ can be saved and the latency can be reduced.
 To verify if `APIResponseCompression` is working, you can send a **get** or **list** request to the
 API server with an `Accept-Encoding` header, and check the response size and headers. For example:
 
-```
+```http
 GET /api/v1/pods
 Accept-Encoding: gzip
 ---
@@ -592,7 +591,7 @@ of 500 pods at a time, request those chunks as follows:
 
 1. List all of the pods on a cluster, retrieving up to 500 pods each time.
 
-   ```
+   ```http
    GET /api/v1/pods?limit=500
    ---
    200 OK
@@ -613,7 +612,7 @@ of 500 pods at a time, request those chunks as follows:
 
 1. Continue the previous call, retrieving the next set of 500 pods.
 
-   ```
+   ```http
    GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
    ---
    200 OK
@@ -634,7 +633,7 @@ of 500 pods at a time, request those chunks as follows:
 
 1. Continue the previous call, retrieving the last 253 pods.
 
-   ```
+   ```http
    GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
    ---
    200 OK
@@ -655,7 +654,7 @@ of 500 pods at a time, request those chunks as follows:
 Notice that the `resourceVersion` of the collection remains constant across each request,
 indicating the server is showing you a consistent snapshot of the pods. Pods that
 are created, updated, or deleted after version `10245` would not be shown unless
-you make a separate **list** request without the `continue` token.  This allows you
+you make a separate **list** request without the `continue` token. This allows you
 to break large requests into smaller chunks and then perform a **watch** operation
 on the full set without missing any updates.
 
@@ -682,7 +681,7 @@ has `kind` set to
 [`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList);
 each item in that collection represents a single Service. For example:
 
-```
+```http
 GET /api/v1/services
 ```
 
@@ -779,7 +778,7 @@ type.
 
 For example, list all of the pods on a cluster in the Table format.
 
-```
+```http
 GET /api/v1/pods
 Accept: application/json;as=Table;g=meta.k8s.io;v=v1
 ---
@@ -800,7 +799,7 @@ For API resource types that do not have a custom Table definition known to the c
 plane, the API server returns a default Table response that consists of the resource's
 `name` and `creationTimestamp` fields.
 
-```
+```http
 GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
 ---
 200 OK
@@ -844,7 +843,7 @@ Accept: application/json;as=Table;g=meta.k8s.io;v=v1, application/json
 When you **delete** a resource this takes place in two phases.
 
 1. _finalization_
-2. removal
+1. removal
 
 ```yaml
 {
@@ -857,7 +856,8 @@ When you **delete** a resource this takes place in two phases.
 }
 ```
 
-When a client first sends a **delete** to request the removal of a resource, the `.metadata.deletionTimestamp` is set to the current time.
+When a client first sends a **delete** to request the removal of a resource,
+the `.metadata.deletionTimestamp` is set to the current time.
 Once the `.metadata.deletionTimestamp` is set, external controllers that act on finalizers
 may start performing their cleanup work at any time, in any order.
 
@@ -896,8 +896,12 @@ the **delete** and **unsafe-delete-ignore-read-errors** verbs on the given resou
 {{< /note >}}
 
 A resource is considered corrupt if it can not be successfully retrieved from the
-storage due to a) transformation error (for example: decryption failure), or b) the object
-failed to decode. The API server first attempts a normal deletion, and if it fails with
+storage due to:
+
+- transformation error (for example: decryption failure), or
+- the object failed to decode.
+
+The API server first attempts a normal deletion, and if it fails with
 a _corrupt resource_ error then it triggers the force delete. A force **delete** operation
 is unsafe because it ignores finalizer constraints, and skips precondition checks.
 
@@ -944,18 +948,17 @@ an HTTP request.
 These situations are:
 
 1. The field is unrecognized because it is not in the resource's OpenAPI schema. (One
-   exception to this is for {{< glossary_tooltip
-   term_id="CustomResourceDefinition" text="CRDs" >}} that explicitly choose not to prune unknown
-   fields via `x-kubernetes-preserve-unknown-fields`).
+   exception to this is for {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRDs" >}}
+   that explicitly choose not to prune unknown fields via `x-kubernetes-preserve-unknown-fields`).
 1. The field is duplicated in the object.
 
 ### Validation for unrecognized or duplicate fields {#setting-the-field-validation-level}
 
 {{< feature-state feature_gate_name="ServerSideFieldValidation" >}}
 
 From 1.25 onward, unrecognized or duplicate fields in an object are detected via
-validation on the server when you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`). Possible levels of
-validation are `Ignore`, `Warn` (default), and `Strict`.
+validation on the server when you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`).
+Possible levels of validation are `Ignore`, `Warn` (default), and `Strict`.
 
 `Ignore`
 : The API server succeeds in handling the request as it would without the erroneous fields
@@ -1003,7 +1006,7 @@ Client-side validation will be removed entirely in a future version of kubectl.
 
 {{< note >}}
 
-Prior to Kubernetes 1.25  `kubectl --validate` was used to toggle client-side validation on or off as
+Prior to Kubernetes 1.25, `kubectl --validate` was used to toggle client-side validation on or off as
 a boolean flag.
 
 {{< /note >}}
@@ -1056,7 +1059,7 @@ effects on any request marked as dry runs.
 
 Here is an example dry-run request that uses `?dryRun=All`:
 
-```
+```http
 POST /api/v1/namespaces/test/pods?dryRun=All
 Content-Type: application/json
 Accept: application/json
@@ -1127,14 +1130,14 @@ corresponding HTTP `Content-Type` header:
 : Server Side Apply YAML (a Kubernetes-specific extension, based on YAML).
   All JSON documents are valid YAML, so you can also submit JSON using this
   media type. See [Server Side Apply serialization](/docs/reference/using-api/server-side-apply/#serialization)
-  for more details.  
+  for more details.
   To Kubernetes, this is a **create** operation if the object does not exist,
   or a **patch** operation if the object already exists.
 
 `application/json-patch+json`
 : JSON Patch, as defined in [RFC6902](https://tools.ietf.org/html/rfc6902).
   A JSON patch is a sequence of operations that are executed on the resource;
-  for example `{"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}`.  
+  for example `{"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}`.
   To Kubernetes, this is a **patch** operation.
 
   A **patch** using `application/json-patch+json` can include conditions to
@@ -1145,7 +1148,7 @@ corresponding HTTP `Content-Type` header:
 : JSON Merge Patch, as defined in [RFC7386](https://tools.ietf.org/html/rfc7386).
   A JSON Merge Patch is essentially a partial representation of the resource.
   The submitted JSON is combined with the current resource to create a new one,
-  then the new one is saved.  
+  then the new one is saved.
   To Kubernetes, this is a **patch** operation.
 
 `application/strategic-merge-patch+json`
@@ -1333,23 +1336,23 @@ Any
 Most recent
 : Return data at the most recent resource version. The returned data must be
   consistent (in detail: served from etcd via a quorum read).
-  For etcd v3.4.31+ and v3.5.13+ Kubernetes {{< skew currentVersion >}} serves “most recent” reads from the _watch cache_:
+  For etcd v3.4.31+ and v3.5.13+, Kubernetes {{< skew currentVersion >}} serves “most recent” reads from the _watch cache_:
   an internal, in-memory store within the API server that caches and mirrors the state of data
   persisted into etcd. Kubernetes requests progress notification to maintain cache consistency against
-  the etcd persistence layer. Kubernetes versions v1.28 through to v1.30 also supported this
+  the etcd persistence layer. Kubernetes v1.28 through to v1.30 also supported this
   feature, although as Alpha it was not recommended for production nor enabled by default until the v1.31 release.
 
 Not older than
 : Return data at least as new as the provided `resourceVersion`. The newest
   available data is preferred, but any data not older than the provided `resourceVersion` may be
-  served.  For **list** requests to servers that honor the `resourceVersionMatch` parameter, this
+  served. For **list** requests to servers that honor the `resourceVersionMatch` parameter, this
   guarantees that the collection's `.metadata.resourceVersion` is not older than the requested
   `resourceVersion`, but does not make any guarantee about the `.metadata.resourceVersion` of any
   of the items in that collection.
 
 Exact
 : Return data at the exact resource version provided. If the provided `resourceVersion` is
-  unavailable, the server responds with HTTP 410 "Gone".  For **list** requests to servers that honor the
+  unavailable, the server responds with HTTP `410 Gone`. For **list** requests to servers that honor the
   `resourceVersionMatch` parameter, this guarantees that the collection's `.metadata.resourceVersion`
   is the same as the `resourceVersion` you requested in the query string. That guarantee does
   not apply to the `.metadata.resourceVersion` of any items within that collection.
@@ -1370,7 +1373,7 @@ the object is when served.
 {{< /note >}}
 
 When using `resourceVersionMatch=NotOlderThan` and limit is set, clients must
-handle HTTP 410 "Gone" responses. For example, the client might retry with a
+handle HTTP `410 Gone` responses. For example, the client might retry with a
 newer `resourceVersion` or fall back to `resourceVersion=""`.
 
 When using `resourceVersionMatch=Exact` and `limit` is unset, clients must
@@ -1395,11 +1398,7 @@ For **watch**, the semantics of resource version are:
 The meaning of those **watch** semantics are:
 
 Get State and Start at Any
-: {{< caution >}} Watches initialized this way may return arbitrarily stale
-  data. Please review this semantic before using it, and favor the other semantics
-  where possible.
-  {{< /caution >}}
-  Start a **watch** at any resource version; the most recent resource version
+: Start a **watch** at any resource version; the most recent resource version
   available is preferred, but not required. Any starting resource version is
   allowed. It is possible for the **watch** to start at a much older resource
   version that the client has previously observed, particularly in high availability
@@ -1410,6 +1409,12 @@ Get State and Start at Any
   watch events are for all changes that occurred after the resource version the
   **watch** started at.
 
+  {{< caution >}}
+  **watches** initialized this way may return arbitrarily stale
+  data. Please review this semantic before using it, and favor the other semantics
+  where possible.
+  {{< /caution >}}
+
 Get State and Start at Most Recent
 : Start a **watch** at the most recent resource version, which must be consistent
   (in detail: served from etcd via a quorum read). To establish initial state,
@@ -1450,8 +1455,8 @@ then the API server may either:
   should wait before retrying the request.
 
 If you request a resource version that an API server does not recognize, the
-kube-apiserver additionally identifies its error responses with a "Too large resource
-version" message.
+kube-apiserver additionally identifies its error responses with a message
+`Too large resource version`.
 
 If you make a **watch** request for an unrecognized resource version, the API server
 may wait indefinitely (until the request timeout) for the resource version to become