REST API should auto-default kind and apiVersion on POST/PUT operations

[abonas]

Why is there a need in 'apiVersion' property in all REST entities?
The client accesses the api already when specifying the version in the url so the client is fully aware which api version was called.
Will there be cases when user approaches v1beta3 and will receive entities with apiVersion=v1beta1 ?
In other words - what's the reason/use case for this attribute?

[bgrant0607]

Serialized representations of the api objects need it, such as:

• The apiserver stores the objects in etcd in versioned format.
• The same schemas are used for declarative configuration. apiVersion tells kubectl which version to use.

[abonas]

@bgrant0607 I understand you might use it for internal implementations (though how would the same service look like when exposed via v1beta1 and v1beta3 on the same server? won't it look the same?) But why is it exposed as part of the REST representation to clients? Can REST api consumers ignore it when they read entities and/or not pass it when they create entities via REST? I assume that the server can populate that property if needed based on the api version it was called with, no?

[bgrant0607]

/cc @smarterclayton, can you think of any problems with automatically populating apiVersion in the apiserver? It looks like we'd have to pass the version into handleRESTStorage and that it might be most straightforward to attempt to inject it before calling DecodeInto.

/cc @nikhiljindal

[smarterclayton]

apiVersion, kind, resource name, resource version, and resource type are all examples of attributes that the apiserver needs to deal with prior to rest storage, that should be verified against a request body. We don't do a very good job today of passing that info down to RESTStorage in a way that validates things correctly. We should.

PUT /pods/bar {"Name":"foo"}

should fail, but it doesn't

In general, REST encourages you to treat the request body as a total unit and not cheat by accepting partial resources. That's more of a guideline (server should be lenient where it's not harmful).

However, the point of apiVersion being in the REST responses and submissions is to provide additional validation, and allow consumers to easily do curl http://.../api/v1beta1/pods/bar > bar.json && kubectl create -f bar.json -s <some other server>. So I don't see any reason to remove it, but it probably should not be required.

[abonas]

@smarterclayton
1.Will v1beta1 be decommissioned once v1beta3 comes out, or both of api versions will continue to "live" in parallel on the servers in the future?
2. if user sends an entity with apiVersion=X to url of apiVersion Y (on same server or like in your example to another server), is there any validation/error on server side?

[smarterclayton]

On Dec 18, 2014, at 10:43 AM, abonas notifications@github.com wrote:

@smarterclayton
1.Will v1beta1 be decommissioned once v1beta3 comes out, or both of api versions will continue to "live" in parallel on the servers in the future?

For some time. We will try to remove v1beta1/2 for Kube 1.0.
2. if user sends an entity with apiVersion=X to url of apiVersion Y (on same server or like in your example to another server), is there any validation/error on server side?

Technically yes (decode will convert what you send into the internal version). Behavior on the server is not versioned today. There are no version differences today where behavior changes across api version, so it's just not something we've dealt with.
—
Reply to this email directly or view it on GitHub.

[jbeda]

It is worth noting that we realize that API stability is important. After we have a true v1 API, we will commit to continue to support that API for some time. This is on our Roadmap around API deprecation policy.

[bgrant0607]

We should verify and/or auto-default Kind the same way as ApiVersion.

[lavalamp]

But why is it exposed as part of the REST representation to clients?

It allows for the possibility of endpoints to return multiple objects of disparate types, for example.

Can REST api consumers ignore it when they read entities and/or not pass it when they create entities via REST?

Yes - as long as the REST client has some way of knowing what type the objects are. e.g., kubectl create -f blah.json figures out what to do with that .json file by looking at .kind & .apiVersion.

I assume that the server can populate that property if needed based on the api version it was called with, no?

Yes, currently the server will assume you are sending it the correct kind of object even if you omit .kind and .apiVersion.

[lavalamp]

Behavior on the server is not versioned today. There are no version differences today where behavior changes across api version, so it's just not something we've dealt with.

It's worth noting that behavior stability and api stability are orthogonal axes. We've got mechanisms and plans to provide api stability already, because forcing clients to churn along with us provides a really bad experience.

Behavior stability is something we'll think harder about when we have correct behaviors that we want to preserve. :) Until we get to that point, we'll be providing behavior improvements (hopefully) over time. There was talk at our testing meeting of providing a list of "behavior" tags from the server (along with its build number) so that tests could figure out if the cluster they're testing should have the behavior they're testing.