Overall API conventions are described in the API文件描述及約定規範 API conventions doc.
API endpoints, 資源型別和示例在api引用中進行了描述。
Remote access to the API is discussed in the api文件遠端訪問 Controlling API Access doc.
kubernetes api還充當系統宣告性配置模式的基礎。kubectl命令列工具可用於建立、更新、刪除和獲取api物件。
kubernetes還根據api資源儲存其序列化狀態（當前在etcd中）。
kubernetes本身被分解為多個元件，這些元件通過其api進行互動。
- API changes
- OpenAPI and Swagger definitions
- API versioning
- API groups
- Enabling API groups
- Enabling resources in the groups
api-changes
根據我們的經驗，任何成功的系統都需要隨著新用例的出現或現有用例的改變而增長和改變。因此，我們期望kubernetes api不斷變化和增長。但是，我們打算在很長一段時間內不破壞與現有客戶機的相容性。通常，新的API資源和新的資源欄位可以被頻繁地新增。消除資源或欄位將需要遵循API棄用策略。
什麼構成相容的更改以及如何更改api由api更改文件詳細說明。
簡而言之api的規範
修改策略
API change document.
遺棄策略
API deprecation policy
openapi和swagger定義
| Header | Possible Values |
|---|---|
| Accept | application/json, application/com.github.proto-openapi.spec.v2@v1.0+protobuf (the default content-type is application/json for */* or not passing this header) |
| Accept-Encoding | gzip (not passing this header is acceptable) |
在1.14之前，格式分離的端點（/swagger.json，/swagger-2.0.0.json，/swagger-2.0.0.pb-v1，/swagger-2.0.0.pb-v1.gz）以不同的格式提供openapi規範。這些端點已棄用，並在Kubernetes 1.14中刪除。
獲取openapi規範的示例：
| Before 1.10 | Starting with Kubernetes 1.10 |
|---|---|
| GET /swagger.json | GET /openapi/v2 Accept: application/json |
| GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf |
| GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf Accept-Encoding: gzip |
kubernetes為api實現了另一種基於protobuf的序列化格式，該格式主要用於叢集內通訊，在設計方案中有記錄，每個模式的idl檔案位於定義api物件的go包中。
在1.14之前，Kubernetes apiserve還公開了一個API，可以用來檢索Swagger v1.2 Kubernetes API規範//swaggerapi。此方法已棄用，並將在Kubernetes 1.14中刪除。
API版本控制
為了更容易消除欄位或重新構造資源表示，kubernetes支援多個api版本，每個版本位於不同的api路徑，例如/api/v1 or /apis/extensions/v1beta1.
我們選擇在api級別而不是在資源或欄位級別進行版本轉換，以確保api呈現出系統資源和行為的清晰、一致的檢視，並允許控制對生命週期結束和/或實驗性api的訪問。json和protobuf序列化模式遵循相同的模式更改準則-下面的所有描述都涵蓋這兩種格式。