Clearly separate compatibility rules for input and output schemas. #851
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ePaul
commented
Oct 7, 2025
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| * Consider <<251>> in case a URL has to change. |
There was a problem hiding this comment.
ePaul
commented
Oct 8, 2025
ePaul
force-pushed
the
compatibility-separately-for-input-output
branch
from
7154a27 to
099c0c6
Compare
ePaul
added
the
major
|
|
||
| API designers should apply the following rules to evolve RESTful APIs for | ||
| services in a backward-compatible way: | ||
| services in a backward-compatible way. |
There was a problem hiding this comment.
Suggested change
| services in a backward-compatible way. | |
| services in a compatible way. |
|
|
||
| * Add only optional, never mandatory fields. | ||
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) |
There was a problem hiding this comment.
Suggested change
| customer-number to customer-id, as both are different unique customer keys) | |
| customer-number to customer-id, both being unique, but different customer keys) |
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| * Consider <<251>> in case a URL has to change. |
| * Never change the semantic of fields (e.g. changing the semantic from | ||
| customer-number to customer-id, as both are different unique customer keys) | ||
| * Consider <<251>> in case a URL has to change. | ||
|
|
There was a problem hiding this comment.
Suggested change
| The compatibility of schema changes depends on whether the input and/or output objects are defined. | |
| customer-number to customer-id, as both are different unique customer keys) | ||
| * Consider <<251>> in case a URL has to change. | ||
|
|
||
| For schemas used in input only: |
There was a problem hiding this comment.
Suggested change
| For schemas used in input only: | |
| For schemas only used for *input objects*: |
| it then would allow later to add a same-named field with different type | ||
| or semantic (which is harder to catch). Therefore, this is also considered a non-compatible change. | ||
| * `enum` ranges can be reduced when used as output. | ||
| * `enum` ranges **cannot** be extended when used for output — clients may |
There was a problem hiding this comment.
Suggested change
| * `enum` ranges **cannot** be extended when used for output — clients may | |
| * `enum` ranges *cannot* be extended — clients may |
| * You <<112>> that are used for output parameters and likely to | ||
| be extended with growing functionality. The API definition should be updated | ||
| first before returning new values. | ||
|
|
There was a problem hiding this comment.
Suggested change
| (*) Hint: Removing an optional field can be considered as a compatible change that does not break clients. However, removed fields allow later adding a same-named field with different type or semantic (which is harder to catch). We therefore define optional field removal as non-compatible. | |
| be extended with growing functionality. The API definition should be updated | ||
| first before returning new values. | ||
|
|
||
| For schemas used in both input and output (which is common and recommended in |
There was a problem hiding this comment.
Suggested change
| For schemas used in both input and output (which is common and recommended in | |
| For schemas used in both input and output (which is typical in |
Comment on lines
+89
to
99
| * Add only optional, never mandatory fields. | ||
| * Don't remove any fields. | ||
| * Don't make mandatory fields optional or make optional fields mandatory. | ||
| * Input fields may have (complex) constraints being validated via server-side | ||
| business logic. Never change the validation logic to be more restrictive and | ||
| make sure that all constraints are clearly defined in description. | ||
| * `enum` ranges can be reduced only if the server is ready to still accept and | ||
| handle old values. They **cannot** be extended. | ||
| * You <<112>> that are used for output parameters and likely to | ||
| be extended with growing functionality. The API definition should be updated | ||
| first before returning new values. |
There was a problem hiding this comment.
Suggested change
| * Add only optional, never mandatory fields. | |
| * Don't remove any fields. | |
| * Don't make mandatory fields optional or make optional fields mandatory. | |
| * Input fields may have (complex) constraints being validated via server-side | |
| business logic. Never change the validation logic to be more restrictive and | |
| make sure that all constraints are clearly defined in description. | |
| * `enum` ranges can be reduced only if the server is ready to still accept and | |
| handle old values. They **cannot** be extended. | |
| * You <<112>> that are used for output parameters and likely to | |
| be extended with growing functionality. The API definition should be updated | |
| first before returning new values. |
There was a problem hiding this comment.
This is is a consequence of the sentence before, and redundant -- should be omitted.
| * Consider <<251>> in case a URL has to change. | ||
|
|
||
| Input/Output here is from the perspective of a service implementing and | ||
| owning the API. For the rare case of APIs implemented by other services |
There was a problem hiding this comment.
Suggested change
| owning the API. For the rare case of APIs implemented by other services | |
| owning the API. For the rare case of call-back APIs implemented by other services |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Triggered by a discussion in an internal chat (internal link), this makes it clearer which of the compatibility rules apply for input and output schemas, respectively.