Backward Compatibility Rules
There are a few simple rules, and a couple of exceptions.
- Requests: do not add mandatories (e.g. adding a new mandatory field, making an optional field mandatory)
- Responses: do not remove mandatories (e.g. remove a mandatory field, make a mandatory field optional)
- Do not change value types (e.g. int to string)
Requests
Do not add mandatory keys and / or make values non-nullable for existing keys.
| Operation | Verdict | Reason |
|---|---|---|
| Add a mandatory key | incompatible | Existing consumers must send a key that they were not sending before. |
| Add an optional key | compatible | Existing consumers are not sending this key anyway, but new consumers may do so. |
| Remove a mandatory key | incompatible (exception) | EXCEPTION Consumers can send the key but server will henceforth ignore it, which could break consumers assumptions. |
| Remove an optional key | incompatible (exception) | If consumers choose to send the key, the server will now ignore it, which could break consumers assumptions. |
| Optional key becomes mandatory | incompatible | Consumers who were not sending this key before will now be expected to send it. |
| Mandatory key becomes optional | compatible | Consumers who were sending this key before can either continue sending it or stop sending it. |
Responses
Do not remove mandatory keys and / or make values nullable for existing gkeys.
| Operation | Verdict | Reason |
|---|---|---|
| Add a mandatory key | compatible | Older consumers were not expecting this key and will ignore it. |
| Add an optional key | compatible | Older consumers were not expecting this key and will ignore it. The server may or may not send it, and consumers should be prepared for either. |
| Remove a mandatory key | incompatible | Older consumers were expecting this key, but henceforth the response will not contain it. |
| Remove an optional key | incompatible | In some cases, the server used to send this in the response. Henceforth it never will. |
| Optional key becomes mandatory | compatible | Sometimes the server didn't send this key. But henceforth, the server will always send this key. Consumers who ignored it before can continue doing so. Consumers who checked for it before have code to handle it. |
| Mandatory key becomes optional | incompatible | It's possible that the server will not send this key. Some consumers may be expecting it, but will not be receiving it henceforth. |