Proposal: v1beta3 API overhaul

Speculative change for some items from #1200:

* Metadata that applies to resources is split from APIMetadata on non-resource API objects
* Metadata is a sub field of objects
* Labels are on Metadata
* Pod current and desired state is split
* Name is used for pods instead of ID (UID is part of metadata, Name is part of resource) for idempotent creation #148 and #1216 
* PodTemplate is a Metadata carrying object as per #170
 * If replicationController gave way to a generic "replicator", then pod template could be both a nested struct and a real resource.
* A ScheduledPod and ScheduledPodList is what the kubelet sees as per #860
* Non-schema'd k/v values on Metadata as `Config` (better names welcome) as per #1201

Not changed yet:

* ReplicationControllers
* Services

EDIT: Moving to higher bandwidth document here: https://docs.google.com/document/d/1E_HNsbyocweD9zJHXbz5Xb9XPwBqvDnLHhGeBq15FlI/edit?usp=sharing
Neither.  I can vague this up (or we could spawn an issue to implement it and clarify).

> On Sep 26, 2014, at 5:23 PM, bgrant0607 <notifications@github.com> wrote:
> 
> In docs/api-conventions.md:
> 
> > +
> > +* GET /watch/<resourceNamePlural> - Receive a stream of JSON objects corresponding to changes made to any resource of the given kind over time.
> > +* GET /watch/<resourceNamePlural>/<name> - Receive a stream of JSON objects corresponding to changes made to the named resource of the given kind over time
> > +* GET /redirect/<resourceNamePlural>/<name> - If the named resource can be described by a URL, return an HTTP redirect to that URL instead of a JSON response. For example, a service exposes a port and IP address and a client could invoke the redirect verb to receive an HTTP 307 redirection to that port and IP.
> > +
> > +Support of additional verbs is not required for all object types.
> > +
> > +
> > +Idempotency
> > +-----------
> > +
> > +All compatible Kubernetes APIs MUST support "name idempotency" and respond with an HTTP status code 409 when a request is made to POST an object that has the same name as an existing object in the system. See [identifiers.md](identifiers.md) for details.
> > +
> > +TODO: name generation
> > +
> > +APIs SHOULD set resourceVersion on retrieved resources, and support PUT idempotency by rejecting HTTP requests with a 409 HTTP status code where an HTTP header `If-Match: resourceVersion=` or `?resourceVersion=` query parameter are set and do not match the currently stored version of the resource.
> Which approach do we support now?
> 
> —
> Reply to this email directly or view it on GitHub.