apiVersion/kind exist on top-level REST responses (GET/LIST, WATCH events), but not on individual items within a LIST response

[abonas]

'kind' property exists only on the outer entity in REST api hence providing not aligned behavior for REST api consumers.
Example: when querying for all services (/api/v1beta1/services) there's an attribute
"kind": "ServiceList" on the collection, but in the "items" section with the actual services - none of the services has the "kind" attribute.
But when querying for a specific service, for example:
http://localhost:8080/api/v1beta1/services/kubernetes-ro
There is a "kind": "Service" on the entity.

I don't see the necessity to have the "kind" property in the first place since the user knows which resource was called by the api specific url, but even if it has a reason and is by design, the entities attributes should be identical whether retrieved as a single entity or as a collection. Otherwise the client should be adding/deleting attributes when retrieved as a collection by their collection type - which is doable, but definitely not elegant.
In other words, either "kind" should be present in each entity when retrieved in bulk AND when retrieved as a single entity, or not present at all for all cases.

[bgrant0607]

Thanks for the report. I agree kind should always be present. Lists have other inconsistencies that need to be fixed, also -- see #2740.

As for why we need kind, we need it for the same reasons as apiVersion (#3000) -- serialized representations, and in cases where we provide GET/WATCH of multiple kinds of objects.

[lavalamp]

Yeah, we made a decision a while ago not to fill in redundant 'kind'/'apiVersion' fields, but we can revisit that.

Once data is marshalled into a go struct, the kind/apiVersion fields are redundant with the type information, so we have the rule that they're always set on the wire and unset in memory. This rule wouldn't (necessarily) make sense for dynamically typed languages.

A consequence of that is that we decided not to recursively set (on the wire) the kind fields on embedded objects of known types, since once you know the enclosing type, you can deduce the other types. But I can see how this would be awkward for non-go clients.

Types with sub-objects that are determined at runtime (see the generic List type that @smarterclayton recently added) are different. For those, we emit version/kind for each sub object, since you cannot deduce this information from the enclosing type.

I can think about a general solution to this if it's important. It'll probably be a bit of a pain to change, though.

[abonas]

@lavalamp thanks for the long explanation.
Consider a ruby client or a Java client consuming the api and converting the json response to objects - it will have to have some "if"s to populate the kind attribute or omit it because otherwise the objects won't be symmetrical, and it can also make some noise when comparing 2 objects. So it's solve-able on client sides, but I'd say it's better to solve it once on server side for all clients.

[bgrant0607]

This would also be fixed by not returning the full bodies of the objects on LIST. :-)

[lavalamp]

I like that fix best of all!

[abonas]

@bgrant0607 this can be problematic for clients because in some cases they'll need afterwards to go to server for each entity again, and that's not effective.
What are you planning not to return in LIST? which part of entities?
BTW this could also be solved by providing support with a flag that clients pass - by default you could pass shallow entities, and with that flag - full entities.

[lavalamp]

Yeah, making full objects/list only configurable + adding kind/apiVersion deeply is probably best.

[abonas]

@lavalamp , on the same topic - what's the expectation from clients creating (POST) a new object - must they fill 'kind' attribute? I mean it's possible to pass it, but not very standard since you already create it on some resource (/services).
I tried creating without this property and it works fine, but it's important to understand what's the 'formal' expectation.

[lavalamp]

Yes, the server can deduce kind & apiVersion, so they're not required for POSTs or PUTs.

Specifying an incorrect kind for the URL you're using will cause an error. Specifying a different version than is in your URL will cause the server to convert your request appropriately (liberal in what it accepts).

[smarterclayton]

Actually, with the pending renames to minion you can pass both kind "node" and kind "minion" to the v1beta1/2 api endpoints. This is to make backwards compatibility easier.

On Dec 21, 2014, at 3:28 PM, Daniel Smith notifications@github.com wrote:

Yes, the server can deduce kind & apiVersion, so they're not required for POSTs or PUTs.

Specifying an incorrect kind for the URL you're using will cause an error. Specifying a different version than is in your URL will cause the server to convert your request appropriately (liberal in what it accepts).

—
Reply to this email directly or view it on GitHub.

[lavalamp]

Oh, true-- I forgot about that exception.