Move API overview to be a Docsy section overview

Author: Tim Bannister

content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md

@@ -16,7 +16,7 @@ methods for adding custom resources and how to choose between them.
 <!-- body -->
 ## Custom resources
 
-A *resource* is an endpoint in the [Kubernetes API](/docs/reference/using-api/api-overview/) that stores a collection of
+A *resource* is an endpoint in the [Kubernetes API](/docs/concepts/overview/kubernetes-api/) that stores a collection of
 [API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a certain kind; for example, the built-in *pods* resource contains a collection of Pod objects.
 
 A *custom resource* is an extension of the Kubernetes API that is not necessarily available in a default

content/en/docs/concepts/overview/kubernetes-api.md

@@ -103,8 +103,8 @@ and behavior, and to enable controlling access to end-of-life and/or
 experimental APIs.
 
 To make it easier to evolve and to extend its API, Kubernetes implements
-[API groups](/docs/reference/using-api/api-overview/#api-groups) that can be
-[enabled or disabled](/docs/reference/using-api/api-overview/#enabling-or-disabling).
+[API groups](/docs/reference/using-api/#api-groups) that can be
+[enabled or disabled](/docs/reference/using-api/#enabling-or-disabling).
 
 API resources are distinguished by their API group, resource type, namespace
 (for namespaced resources), and name. The API server may serve the same
@@ -115,7 +115,7 @@ versions `v1` and `v1beta1` for the same resource. An object created by the
 `v1beta1` version can then be read, updated, and deleted by either the
 `v1beta1` or the `v1` versions.
 
-Refer to [API versions reference](/docs/reference/using-api/api-overview/#api-versioning)
+Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
 for more details on the API version level definitions.
 
 ## API Extension

content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md

@@ -91,9 +91,9 @@ and the `spec` format for a Deployment can be found in
 
 ## {{% heading "whatsnext" %}}
 
-* [Kubernetes API overview](/docs/reference/using-api/api-overview/) explains some more API concepts
 * Learn about the most important basic Kubernetes objects, such as [Pod](/docs/concepts/workloads/pods/).
-* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes
+* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes.
+* [Using the Kubernetes API](/docs/reference/using-api/) explains some more API concepts.
 
 
 

content/en/docs/reference/_index.md

@@ -18,8 +18,8 @@ This section of the Kubernetes documentation contains references.
 
 ## API Reference
 
-* [Kubernetes API Overview](/docs/reference/using-api/api-overview/) - Overview of the API for Kubernetes.
 * [Kubernetes API Reference {{< latest-version >}}](/docs/reference/generated/kubernetes-api/{{< latest-version >}}/)
+* [Using The Kubernetes API](/docs/reference/using-api/) - overview of the API for Kubernetes.
 
 ## API Client Libraries
 

content/en/docs/reference/access-authn-authz/authorization.md

@@ -52,7 +52,7 @@ Kubernetes reviews only the following API request attributes:
  * **Resource** - The ID or name of the resource that is being accessed (for resource requests only) -- For resource requests using `get`, `update`, `patch`, and `delete` verbs, you must provide the resource name.
  * **Subresource** - The subresource that is being accessed (for resource requests only).
  * **Namespace** - The namespace of the object that is being accessed (for namespaced resource requests only).
- * **API group** - The {{< glossary_tooltip text="API Group" term_id="api-group" >}} being accessed (for resource requests only). An empty string designates the [core API group](/docs/reference/using-api/api-overview/#api-groups).
+ * **API group** - The {{< glossary_tooltip text="API Group" term_id="api-group" >}} being accessed (for resource requests only). An empty string designates the _core_ [API group](/docs/reference/using-api/#api-groups).
 
 ## Determine the Request Verb
 

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

@@ -1,4 +1,129 @@
 ---
-title: Using the Kubernetes API
+title: Kubernetes API Overview
+reviewers:
+- erictune
+- lavalamp
+- jbeda
+content_type: concept
 weight: 10
----
+card:
+  name: reference
+  weight: 50
+  title: Overview of API
+---
+
+<!-- overview -->
+
+This section provides reference information for the Kubernetes API.
+
+The REST API is the fundamental fabric of Kubernetes. All operations and
+communications between components, and external user commands are REST API
+calls that the API Server handles. Consequently, everything in the Kubernetes
+platform is treated as an API object and has a corresponding entry in the
+[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
+
+The [Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
+lists the API for Kubernetes version {{< param "version" >}}.
+
+For general background information, read
+[The Kubernetes API](/docs/concepts/overview/kubernetes-api/).
+
+<!-- body -->
+
+The REST API is the fundamental fabric of Kubernetes. All operations and
+communications between components, and external user commands are REST API
+calls that the API Server handles. Consequently, everything in the Kubernetes
+platform is treated as an API object and has a corresponding entry in the
+API.
+
+## API versioning
+
+The JSON and Protobuf serialization schemas follow the same guidelines for
+schema changes. The following descriptions cover both formats.
+
+The API versioning and software versioning are indirectly related.
+The [API and release versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
+describes the relationship between API versioning and software versioning.
+
+Different API versions indicate different levels of stability and support. You
+can find more information about the criteria for each level in the
+[API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
+
+Here's a summary of each level:
+
+- Alpha:
+  - The version names contain `alpha` (for example, `v1alpha1`).
+  - The software may contain bugs. Enabling a feature may expose bugs. A
+    feature may be disabled by default.
+  - The support for a feature may be dropped at any time without notice.
+  - The API may change in incompatible ways in a later software release without notice.
+  - The software is recommended for use only in short-lived testing clusters,
+    due to increased risk of bugs and lack of long-term support.
+
+- Beta:
+  - The version names contain `beta` (for example, `v2beta3`).
+  - The software is well tested. Enabling a feature is considered safe.
+    Features are enabled by default.
+  - The support for a feature will not be dropped, though the details may change.
+
+  - The schema and/or semantics of objects may change in incompatible ways in
+    a subsequent beta or stable release. When this happens, migration
+    instructions are provided. Schema changes may require deleting, editing, and
+    re-creating API objects. The editing process may not be straightforward.
+    The migration may require downtime for applications that rely on the feature.
+  - The software is not recommended for production uses. Subsequent releases
+    may introduce incompatible changes. If you have multiple clusters which
+    can be upgraded independently, you may be able to relax this restriction.
+
+  {{< note >}}
+  Please try beta features and provide feedback. After the features exit beta, it
+  may not be practical to make more changes.
+  {{< /note >}}
+
+- Stable:
+  - The version name is `vX` where `X` is an integer.
+  - The stable versions of features appear in released software for many subsequent versions.
+
+## API groups
+
+[API groups](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)
+make it easier to extend the Kubernetes API.
+The API group is specified in a REST path and in the `apiVersion` field of a
+serialized object.
+
+There are several API groups in Kubernetes:
+
+*  The *core* (also called *legacy*) group is found at REST path `/api/v1`.
+   The core group is not specified as part of the `apiVersion` field, for
+   example, `apiVersion: v1`.
+*  The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use
+   `apiVersion: $GROUP_NAME/$VERSION` (for example, `apiVersion: batch/v1`).
+   You can find the full list of supported API groups in
+   [Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-).
+
+## Enabling or disabling API groups   {#enabling-or-disabling}
+
+Certain resources and API groups are enabled by default. You can enable or
+disable them by setting `--runtime-config` on the API server.  The
+`--runtime-config` flag accepts comma separated `<key>[=<value>]` pairs
+describing the runtime configuration of the API server. If the `=<value>`
+part is omitted, it is treated as if `=true` is specified. For example:
+
+ - to disable `batch/v1`, set `--runtime-config=batch/v1=false`
+ - to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1`
+
+{{< note >}}
+When you enable or disable groups or resources, you need to restart the API
+server and controller manager to pick up the `--runtime-config` changes.
+{{< /note >}}
+
+## Persistence
+
+Kubernetes stores its serialized state in terms of the API resources by writing them into
+{{< glossary_tooltip term_id="etcd" >}}.
+
+## {{% heading "whatsnext" %}}
+
+- Learn more about [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
+- Read the design documentation for
+  [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)

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

@@ -12,7 +12,7 @@ API from various programming languages.
 
 
 <!-- body -->
-To write applications using the [Kubernetes REST API](/docs/reference/using-api/api-overview/),
+To write applications using the [Kubernetes REST API](/docs/reference/using-api/),
 you do not need to implement the API calls and request/response types yourself.
 You can use a client library for the programming language you are using.
 

content/en/docs/reference/using-api/client-libraries.md

@@ -24,7 +24,7 @@ a deprecation policy for aspects of the system that are slated to be removed.
 Since Kubernetes is an API-driven system, the API has evolved over time to
 reflect the evolving understanding of the problem space. The Kubernetes API is
 actually a set of APIs, called "API groups", and each API group is
-independently versioned.  [API versions](/docs/reference/using-api/api-overview/#api-versioning) fall
+independently versioned.  [API versions](/docs/reference/using-api/#api-versioning) fall
 into 3 main tracks, each of which has different policies for deprecation:
 
 | Example  | Track                            |

content/en/docs/reference/using-api/deprecation-policy.md

@@ -68,6 +68,7 @@
 /docs/api/     /docs/concepts/overview/kubernetes-api/ 301
 
 /docs/api-reference/labels-annotations-taints/     /docs/reference/labels-annotations-taints/ 301
+/docs/reference/using-api/api-overview/     /docs/reference/using-api/ 301
 
 /docs/concepts/abstractions/controllers/garbage-collection/     /docs/concepts/workloads/controllers/garbage-collection/ 301
 /docs/concepts/abstractions/controllers/statefulsets/     /docs/concepts/workloads/controllers/statefulset/ 301