search

Azure / openapi-diff

Command line tool to detect breaking changes between two openapi specifications
MIT License
261 stars 36 forks source link

[Rule] Allowed values for an enum have changed #36

Open vishrutshah opened 7 years ago

vishrutshah commented 7 years ago

Enum “foo” had allowed values as “val1” and “val2” in v1 of API. If now, the values allowed/accepted by the service are “val1”, “val2” and “val3”, client will fail to de-serialize if “val3” comes back in the response.

vishrutshah commented 7 years ago

Case 1: Data Direction is Request. If old version has enum in request direction with values "val1" and "val2" then new version adds allowed/accepted value "val3". Result: Breaking Change Reason: old version of SDK will not serialize the value "val3" sent by new version of the api

Case 2: Data Direction is Request. If old version has enum in request direction with values "val1" and "val2" then new version removed allowed/accepted value "val2". Result: Breaking Change Reason: old version of SDK will not serialize the value "val3" to be send to new version of the api

Case 3: Data Direction is Response. If old version has enum in response direction with values "val1" and "val2" then new version adds allowed/accepted value "val3". Result: Breaking Change Reason: old version of SDK will not de-serialize the value "val3" sent by new version of the api

Case 4: Data Direction is Response. If old version has enum in response direction with values "val1" and "val2" then new version removed allowed/accepted value "val2". Result: Non-Breaking Change

vishrutshah commented 7 years ago

@ravbhatnagar @amarzavery @johanste Could you please help me verify these cases? Let me know your views. Thanks!

vishrutshah commented 7 years ago

Discussed with @johanste offline, and all of these are considered a breaking changes.

johanste commented 7 years ago

In the context of Azure/RPC and how they are described in Swagger, I would argue that all 4 cases above introduce breaking changes (Azure in general has a very strict definition of breaking changes).

For the fourth case, if a service simply stopped ever returning val3, but never removed it as a possibility, it would not be a breaking change unless semantically, it changed the contract (for a semantically breaking change, consider an API that, given a name, returned an enum value indicating if the name was available, taken or malformed. To change the API to never return that the name is taken would change the overall contract and thus be breaking)