Clarify guidance for returning resources across api-versions

[annelo-msft]

For client development, it is important to know what a service will return in the following situation:

1. In service v1, there is a resource Foo with one property Bar, and operations to GET and PUT Foo.
2. In service version 2, an optional property Baz is added to Foo. Assuming the service holds a resource Foo { Bar='a', Baz='b' },
   • GET Foo with api-version=v2 will return Foo { Bar='a', Baz='b' }
   • GET Foo with api-version=v1 will return either: A. Foo { Bar='a' } because Baz is unknown in api-version=v1 or B. Foo { Bar='a', Baz='b' } because this represents the full resource

From conversations with @JeffreyRichter, I believe A is recommended, although from conversations with @tg-msft, I believe B is more common in practice.

Would it be possible to clarify what the guidance to services is in this case? Thanks!

[JeffreyRichter]

The answer is A. In fact, this is the main goal of the api-verison query parameter: a v1 client only ever sees what was documented and therefore expects to get. I responded more in email.