Invalid backward compatibility result for new read-only property in PUT operations #136
Comments
trohrberg
pushed a commit
to trohrberg/openapi-diff
that referenced
this issue
Mar 24, 2020
Adding a new read-only property into an API model should be considered a breaking change for PUT operations. A client not knowing of the new read-only property would get a resource from the API which includes the new read-only property and would send a full update back via PUT omitting that new property. The result is that the property would be cleared on the server side as the client did not sent the retrieved value back.
|
@trohrberg Thanks for reporting this! Would it be possible for you to open a pull request in this repository based on trohrberg@25bd154? |
|
Hello joschi, I already provided a pull rqeuest for this issue (#137) and that PR has already been merged. However, I did not check the latest version yet and if the problem is completely solved now. I will do that soon, but you may close this issue anyways. Best regards |
|
Resolved in #137. |
This was referenced Jul 22, 2021
westse
added a commit
to westse/openapi-diff
that referenced
this issue
Jun 28, 2023
Effectively reverts change for OpenAPITools#136 which appears invalid in intent, implementation, and test. - Invalid in intent: OpenAPITools#136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, [per the OAS spec](https://spec.openapis.org/oas/v3.0.3#fixed-fields-19), that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties. - Invalid in implementation: the code treats as incompatible any PUT request property, not just readOnly properties. - Invalid in test: no readOnly properties are tested. In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue.
This was referenced Jun 28, 2023
westse
added a commit
to westse/openapi-diff
that referenced
this issue
Jun 29, 2023
Effectively reverts change for OpenAPITools#136 which appears invalid in intent, implementation, and test. - Invalid in intent: OpenAPITools#136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, [per the OAS spec](https://spec.openapis.org/oas/v3.0.3#fixed-fields-19), that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties. - Invalid in implementation: the code treats as incompatible any PUT request property, not just readOnly properties. - Invalid in test: no readOnly properties are tested. In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue.
westse
added a commit
to westse/openapi-diff
that referenced
this issue
Jun 29, 2023
Effectively reverts change for OpenAPITools#136 which appears invalid in intent, implementation, and test. - Invalid in intent: OpenAPITools#136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, [per the OAS spec](https://spec.openapis.org/oas/v3.0.3#fixed-fields-19), that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties. - Invalid in implementation: the code treats as incompatible any PUT request property, not just readOnly properties. - Invalid in test: no readOnly properties are tested. In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue.
westse
added a commit
to westse/openapi-diff
that referenced
this issue
Jul 21, 2023
Effectively reverts change for OpenAPITools#136 which appears invalid in intent, implementation, and test. - Invalid in intent: OpenAPITools#136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, [per the OAS spec](https://spec.openapis.org/oas/v3.0.3#fixed-fields-19), that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties. - Invalid in implementation: the code treats as incompatible any PUT request property, not just readOnly properties. - Invalid in test: no readOnly properties are tested. In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue.
joschi
pushed a commit
that referenced
this issue
Jul 25, 2023
Effectively reverts change for #136 (and PR #137) which appear invalid in intent, implementation, and test. - Invalid in intent: #136 claims that adding a readOnly property to the request body of a PUT request is a breaking change because clients will begin to omit it and the server will interpret the omission as a directive to delete the property. This is incorrect because the server should expect, [per the OAS spec](https://spec.openapis.org/oas/v3.0.3#fixed-fields-19), that readOnly properties "SHOULD NOT be sent as part of the request". So it would be a bug for the server to delete any data associated with the readOnly property. Regardless, the API is left unbroken if the server simply ignores readOnly properties. - Invalid in implementation: the code treats as incompatible any new PUT request property, not just readOnly properties. - Invalid in test: no readOnly properties are tested. In theory one could argue that some servers might enforce the "SHOULD NOT" language of the spec by returning validation errors where they didn't before, and this would constitute an API breakage. But that should be discussed in a different issue. Fixes #537 Refs #136 Refs #137
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Hi, thank you for creating this tool which helps us a lot in our project. We noticed the following deviation between the tool's responses concerning backward compatibility and our expectation. I would like to discuss that here to see if you agree with our perspective:
We consider the addition of a new read-only property into an API model as a breaking change for PUT operations. A client not knowing of the new read-only property would get a resource from the API which includes the new read-only property and would send a full update back via PUT omitting that new property. The result is that the property would be cleared on the server side as the client did not sent the retrieved value back.
I will shortly provide a pull request fixing this issue (if it is one) and appreciate a lot your comments and opinions on whether this is an issue or not.
The text was updated successfully, but these errors were encountered: