I think this will be big enough already without also tackling multi-resource returns at the same time :)

We have to support list and watch of partial objects. That's not optional.

Yes, but multiple objects in the same call at the same time? (I interpreted "one or more resources" as meaning different kinds of resources rather than multiple objects of the same resource type, which I think is what you meant.)

Correct - will clarify this is access to a single resource type, singular or plural resources

Maybe leave items with fan-out to another proposal--that feels like step two.

I was going to add an example to emphasize I don't believe it should be allowed to deviate from the pattern. Agree it doesn't have to be solved here.

DeleteOptions

UpdateOptions (if it was a thing)

s/clietns/clients/

Although I want to move the legacy group from /api/v1 to /apis/core/v1 if I can talk @bgrant0607 into it. (Which really means serving it at both places for a really long time. But at least new components wouldn't have to build in an exception.)

This group would only contain things that are API machinery or unversioned today, not pods or nodes.

I don't think "server group" is a common term yet, perhaps you can define it.

why are sv and g separate?

I think what you've called "api.k8s.io" I would call "core.k8s.io". We should probably figure out the canonical name.

sv controls the schema I get back on errors (Status in api.k8s.io/v1). If a generic client asks for a response in a particular group version it may still want errors in a known schema, and for back compatibility we can't return Status in the server group by default.

When setting that up initially, we declared that clients had to know what the thing was, and that we'd version it via Accept/Content-Type. So what you're saying here was the original intent.

Yeah, and we need the separate group to give Scale a client discoverable schema.

perhaps do gv, and take the format version.group? Or is version intended to be optional?

We can't do slashes in Accept headers so we'd either need to do individual parts (g and v separate) or use the combined format from kubectl "resource.version.groupName". I prefer the decomposed version because the search rules for the combined format are complex.

I think separating group and version where we can is good, except in cases where we can make an explicit argument that they should be consistent with apiVersion

s/knows/knowns/

groupVersion? Would like to avoid making more things called apiVersion when they actually include the group, too.

also I'd argue again for v1.core.k8s.io.

I was going for strict compatibility with our core object schema. I'd rather use apiVersion consistently on resource operations rather than mix explanations (use apiVersion when you serialize an object to JSON but groupVersion when you serialize an object to query parameters seems wrong to me).

Can you list these 6 implementations that you have in mind?

kubectl, kompose, helm, dashboard, OpenShift web UI (developer console), OpenShift Eclipse client. Will create a small list here as a point in time capture

If I want to get multiple fields, e.g., ObjectMeta+Status.ObservedGeneration, do I need to define another partial API kind? That doesn't sound very flexible.

In practice I believe it's safer and more correct to have a finite set of combinations targeted towards special use cases, rather than some sort of "meta retriever" that takes string JSONPath expressions. For instance, what do you need ObservedGeneration for? To properly implement GC on a subset of controllers that are reactive? The fields that are necessary for GC are just another variant of Scale - an interface for a particular use case. If ObservedGeneration means slightly different things per controller object, the right way is to declare the interface each object supports and expose the correct Og.

Specific schemes (like proto) can be optimized and generated. Generic ones can't. I would argue there are probably no more than 8 generic interfaces over the next year, and it is simpler and easier to generate the right documentation and outcomes for those interfaces to require concrete schemes than to assume field selectors can correctly identity the subset.

Garbage collector needs the ObservedGeneration to know if the controller of the resource (e.g., replicaset) has observed the resource is being deleted, and thus stops creating more dependents (e.g., pods).

I probably can find other approaches so that GC doesn't need to watch ObjectMeta and Status.ObservedGeneration at the same time. I'm asking a general question, and the reasons you listed are reasonable.

What is "Og"?

Og = observed generation.

If we wanted to make controllers identify which generation they've observed formally we could always add it to PartialObjectMeta. But we would need to distinguish between controller knows and controller doesn't know (*int64 maybe) and what would GC do if the controller doesn't set OG?

If the controller doesn't set OG, there will be race between GC and the controller, then GC can't guarantee to orphan/delete all the dependents.

Adding OG to PartialObjectMeta and typed it as *int64 sound good.

Why does the Accept head need "g=api.k8s.io,v=v1,as=Scale"? The kind and version in the body should be enough?

Controls the response from the server (show me the result of the PUT as Scale in server group).

Yes, but multiple objects in the same call at the same time? (I interpreted "one or more resources" as meaning different kinds of resources rather than multiple objects of the same resource type, which I think is what you meant.)

Why not just call it ObjectMetadata?
That way any client knows that if it requires a field X from namespaces, it can go a GET /api/v1/namespaces with Accept as=X.
How does it know that it needs to set as=PartialObjectMetadata for getting ObjectMetadata.

The distinction here is that the type has to have a schema, so the type returned has to have TypeMeta, which ObjectMetadata does not have.

Chai and I used Partial as the top level type for his PR - name can be changed, but prefer to have Go struct name match Kind.

nit: should be /api/v1/namespace/example/replicationcontrollers or /apis/extensions/v1beta1/namespace/example/replicasets

It will also return other fields of Namespace, not only metadata, right? (I mean, spec and status).

Sorry, I should have clarified. It would not:

type PartialObjectMetadata struct {
  TypeMeta `json:",inline"`
  ObjectMeta `json:"metadata"`
}

is the definition of the versioned PartialObjectMetadata. The client asks for a Kind and gets a Kind.

I would like to clarify one thing - IIUC, the value of "as" has to be understood by the server. This means that using this mechanism we will be able to get some well-defined parts of the objects (e.g. metadata), but not the random fields of objects (so in other words, it's not a generic mechanism to support sending only selected fields of objects to client). Right?

Correct, the design described here is "ask the server to return an object matching a known schema", not "ask the server to return parts of an existing schema". I will add that to alternatives to describe in more detail why I think the more generic option is worse for clients and for us in the near term.

Please strip the warning block.