Add more detail about media types #46230
Conversation
k8s-ci-robot
added
wg/api-expression
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
sig/docs
k8s-ci-robot
added
cncf-cla: yes
|
|
||
| <!--more--> | ||
| A manifest specifies the desired state of an object that Kubernetes will maintain when you apply the manifest. Each configuration file can contain multiple manifests. | ||
| A manifest specifies the desired state of an object that Kubernetes will maintain when you apply the manifest. | ||
| For YAML format, each file can contain multiple manifests. |
There was a problem hiding this comment.
I don't think you can put more than one manifest in a file in JSON format, and still call that file “JSON”.
| Although YAML is widely used to define Kubernetes manifests locally, Kubernetes does not | ||
| support the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html) media type | ||
| for API operations. |
There was a problem hiding this comment.
There is application/apply-patch+yaml (and documents in that format look like, uh, JSON). For simplicity I am deliberately not mentioning that detail here. The statement:
Kubernetes does not support the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html)
media type for API operations.remains true.
✅ Pull request preview available for checkingBuilt without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
| ### Kubernetes Protobuf encoding {#protobuf-encoding} | ||
|
|
||
| Kubernetes uses an envelope wrapper to encode [Protobuf](https://protobuf.dev/) responses. | ||
| That wrapper starts with a 4 byte magic number to help identify content in disk or in etcd as Protobuf | ||
| (as opposed to JSON). The 4 byte magic number data is followed by a Protobuf encoded wrapper message, which | ||
| describes the encoding and type of the underlying object. Within the Protobuf wrapper message, | ||
| the inner object data is recorded using the `raw` field of Unknown (see the [IDL](##protobuf-encoding-idl) | ||
| for more detail). |
There was a problem hiding this comment.
Moved, not new. A local diff with git diff --color-moved=… might help show the changes better than GitHub's web UI.
| ``` | ||
| GET /api/v1/pods | ||
| Accept: application/json | ||
| --- | ||
| 200 OK | ||
| Content-Type: application/json | ||
|
|
||
| … JSON encoded collection of Pods (PodList object) | ||
| ``` |
There was a problem hiding this comment.
Adapted from the existing protobuf example
| The Kubernetes API implements standard HTTP content type negotiation: passing an | ||
| `Accept` header with a `GET` call will request that the server tries to return | ||
| a response in your preferred media type. If you want to send an object in Protobuf to | ||
| the server for a `PUT` or `POST` call means that you must set the `Content-Type` | ||
| header appropriately. |
There was a problem hiding this comment.
Moved and adapted, not new. A local diff with git diff --color-moved=… might help show the changes better than GitHub's web UI.
- Add section about JSON encoding for API - Mention that the HTTP API doesn't use YAML
sftim
force-pushed
the
20240506_explain_api_media_types
branch
from
97af243
to
cab0fbc
Compare
Revise https://k8s.io/docs/reference/using-api/api-concepts/
Preview
/wg api-expression
/language en