𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽
"We did not break anything. We just cleaned up the response."
Those words often lead to crashes. A mobile app fails. A partner integration returns garbage. You changed the shape of data that others depend on.
Dangerous changes often look like tidying up. They pass code reviews and tests. The breakage happens in code you cannot see.
Here are nine changes that feel safe but are not.
Renaming fields Changing userId to user_id for consistency breaks clients. A rename is a delete and an add. The delete part breaks people. Safe move: Add the new field. Keep the old one. Deprecate it. Remove it much later.
Making a field optional A field used to be there. Now it is sometimes null. The client code crashes when it tries to process it. Safe move: Treat "always present" as a promise. If a field becomes optional, use a new version.
Removing unused fields You cannot see how your consumers use your data. "Unused" only means unused by you. Safe move: Measure field usage in production before you remove anything.
Narrowing input types Changing a string to an enum or a number to an integer breaks requests. Widening an input is safe. Narrowing it is a breaking change. Safe move: Only loosen the inputs you accept. Tightening requires a new version.
Changing default values Changing a default from false to true changes behavior without an error. This breaks logic silently. Safe move: Treat a default change as a breaking change.
Adding required fields Adding tenantId and making it required breaks every existing client. They will get a 400 error. Safe move: New fields must be optional or use a new version.
Changing error formats Changing a 400 to a 422 or changing the error body breaks error handling code. Safe move: Error formats are contracts. Version them like anything else.
Modifying enum values Renaming "active" to "ACTIVE" breaks clients. Removing a value breaks clients with strict logic. Safe move: Enum values are forever. Add them carefully. Never rename or remove them without a major version.
Changing data meaning Changing a date from Unix seconds to ISO-8601 or changing pagination from offset to cursor breaks everything. A schema diff might not even catch these. Safe move: Pin formats explicitly. Compare real payloads, not just the spec.
Não confie no instinto. Compare cada alteração com o contrato de produção no seu CI. Um humano pode deixar passar um campo renomeado. Uma ferramenta de diff não.
Fonte: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0