Is it possible to deprecate the properties without revising the API version?

[bagajjal]

Is it possible that the .NET SDK schema for a given resource change without revising the underlying AWS REST API version.
For example, EC2 REST API version is "2016-11-15". Over the past 7 years, is there a situation where EC2 resource properties are deprecated? If yes, is it considered as a breaking change or not. What is the AWS guidance on this.

[normj]

Looking into our EC2 history it looks like one resource property has been deprecated back 2019. That would be AssociatedTargetNetworks from on the ClientVPNEndpoint type. We don't consider deprecating properties and operations a breaking change because they still exist and maintain their behavior, at least best they can but newer features might make the behavior of deprecated properties ambiguous. Hence if you use new features you should use the suggest changes in the deprecated message.

[bagajjal]

@normj, thanks for your response.

If a property is deprecated, then AWS service has logic in place NOT to populate the deprecate property i.e., as a client, I don't have a way to fetch the response in the old schema that I have?

What happens if a property is deprecated but there is no replacement with new property. Even in this case, it's not considered as a breaking change?

I was wondering why the API version is not revised. In general, API Version serves as a contract between client and the server that dictates the request and response schema?

[bagajjal]

@normj - ping.

[normj]

I'm not following your question. If a property is deprecated the service still returns back data for the property. The exception is if you use newer features since the property was deprecated that newer feature might not make sense for the deprecated property and in that case the deprecated property might not have a value. So basically the user is opting into new behavior which makes sense the response might be different.

We try very hard to not ship breaking changes. Changing the API version number doesn't really work for making breaking changes because SDKs only generate from the model tip. And it is also really hard to rationalize SDK version numbers with the API version.

[bagajjal]

If a property is deprecated the service still returns back data for the property

Is it guaranteed that all AWS services return the deprecated properties (assuming it's not replaced with new feature) all the time?

To illustrate, consider a scenario with AWS SDK version 1 (V1) interacting with a resource, let's call it resource-A, which initially has two properties (prop1, prop2). Over time, AWS deprecates prop2 and introduces a new property, prop3. Consequently, AWS SDK version 2 (V2) is introduced to support these changes.

If a client is using AWS SDK V1, the response will include prop1 and the deprecated prop2 (with actual value). On the other hand, if the client is utilizing AWS SDK V2, the response will feature prop1 and the newly introduced prop3. This ensures that clients, depending on their SDK version, observe the relevant properties in the API response.

Is my understanding correct?

[bagajjal]

@normj, ping.