kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #391 from smarterclayton/spec_response 

Describe API groups and spec/status for simple kinds
This commit is contained in:
Brian Grant 2017-02-26 17:00:28 -08:00 committed by GitHub
parent f6437c175c 135ff327f1
commit c089c0802f
1 changed files with 32 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
contributors/devel/api-conventions.md
View File

@ -1,7 +1,7 @@
API Conventions API Conventions
=============== ===============
Updated: 4/22/2016 Updated: 2/23/2017
*This document is oriented at users who want a deeper understanding of the *This document is oriented at users who want a deeper understanding of the
Kubernetes API structure, and developers wanting to extend the Kubernetes API. Kubernetes API structure, and developers wanting to extend the Kubernetes API.
@ -74,6 +74,9 @@ kinds would have different attributes and properties)
via HTTP to the server. Resources are exposed via: via HTTP to the server. Resources are exposed via:
* Collections - a list of resources of the same type, which may be queryable * Collections - a list of resources of the same type, which may be queryable
* Elements - an individual resource, addressable via a URL * Elements - an individual resource, addressable via a URL
* **API Group** a set of resources that are exposed together at the same. Along
with the version is exposed in the "apiVersion" field as "GROUP/VERSION", e.g.
"policy.k8s.io/v1".
Each resource typically accepts and returns data of a single kind. A kind may be Each resource typically accepts and returns data of a single kind. A kind may be
accepted or returned by multiple resources that reflect specific use cases. For accepted or returned by multiple resources that reflect specific use cases. For
@ -82,8 +85,17 @@ to create, update, and delete pods, while a separate "pod status" resource (that
acts on "Pod" kind) allows automated processes to update a subset of the fields acts on "Pod" kind) allows automated processes to update a subset of the fields
in that resource. in that resource.
Resources are bound together in API groups - each group may have one or more
versions that evolve independent of other API groups, and each version within
the group has one or more resources. Group names are typically in domain name
form - the Kubernetes project reserves use of the empty group, all single
word names ("extensions", "apps"), and any group name ending in "*.k8s.io" for
its sole use. When choosing a group name, we recommend selecting a subdomain
your group or organization owns, such as "widget.mycompany.com".
Resource collections should be all lowercase and plural, whereas kinds are Resource collections should be all lowercase and plural, whereas kinds are
CamelCase and singular. CamelCase and singular. Group names must be lower case and be valid DNS
subdomains.
## Types (Kinds) ## Types (Kinds)
@ -156,6 +168,16 @@ API endpoints may deviate from the strict REST pattern and return resources that
are not singular JSON objects, such as streams of JSON objects or unstructured are not singular JSON objects, such as streams of JSON objects or unstructured
text log data. text log data.
A common set of "meta" API objects are used across all API groups and are
thus considered part of the server group named `meta.k8s.io`. These types may
evolve independent of the API group that uses them and API servers may allow
them to be addressed in their generic form. Examples are `ListOptions`,
`DeleteOptions`, `List`, `Status`, `WatchEvent`, and `Scale`. For historical
reasons these types are part of each existing API group. Generic tools like
quota, garbage collection, autoscalers, and generic clients like kubectl
leverage these types to define consistent behavior across different resource
types, like the interfaces in programming languages.
The term "kind" is reserved for these "top-level" API types. The term "type" The term "kind" is reserved for these "top-level" API types. The term "type"
should be used for distinguishing sub-categories within objects or subobjects. should be used for distinguishing sub-categories within objects or subobjects.
@ -276,6 +298,14 @@ cannot vary from the user's desired intent MAY have only "spec", and MAY rename
Objects that contain both spec and status should not contain additional Objects that contain both spec and status should not contain additional
top-level fields other than the standard metadata fields. top-level fields other than the standard metadata fields.
Some objects which are not persisted in the system - such as `SubjectAccessReview`
and other webhook style calls - may choose to add spec and status to encapsulate
a "call and response" pattern. The spec is the request (often a request for
information) and the status is the response. For these RPC like objects the only
operation may be POST, but having a consistent schema between submission and
response reduces the complexity of these clients.
##### Typical status properties ##### Typical status properties
**Conditions** represent the latest available observations of an object's **Conditions** represent the latest available observations of an object's