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


----- Original Message -----
> > +   Lists have a limited set of common metadata. All lists use the "items"
> > field to contain the array of objects they return. Each resource kind
> > should have an endpoint that returns the full set of resources, as well as
> > zero or more endpoints that return subsets of the full list.
> > +
> > +The standard REST verbs (defined below) MUST return singular JSON objects.
> > Some 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 text log data.
> > +
> > +
> > +### Resources
> > +
> > +All singular JSON resources returned by an API MUST have the following
> > fields:
> > +
> > +* kind: a string that identifies the schema this object should have
> > +* apiVersion: a string that identifiers the version of the schema the
> > object should have
> > +
> > +
> > +### Objects
> > +
> > +Every object MUST have the following metadata in a nested object field
> > called "metadata":
> 
> Can you remind me why we want this in a sub-object rather than embedded?
> 

To prevent it colliding from other resources or to allow it to grow larger over time without breaking end user names for fields.  It's also easier to ignore and blank out when copying resources. I'm halfway in between wanting it embedded (because that's what the vast majority of APIs do and is simpler to parse for many clients) and wanting it to be cleanly isolated.  Do we expect namespace collisions as we add metadata in the future?  If so, sub object.  Otherwise it's probably easier to inline.