Why Do Some Developers Hate Using Enums in API Design?

Question

A colleague used an enum in an interface definition and was criticized for being hard to extend. Why is this practice disliked?

Author's Explanation

Version upgrades can cause enum classes on both sides to differ, leading to exceptions during interface parsing and class deserialization.

Enums have clear benefits: they are type‑safe, straightforward, can be compared with equality operators, and are usable in switch statements.

However, their main drawback is the inability to extend them.

Parameters are safe because they are decided locally; you only send values that exist in your own enum, ensuring forward compatibility. Return values are problematic because the remote side may introduce new enum constants that your local code does not recognize, causing serialization exceptions.

Example: a local WeatherEnum defines SUNNY, RAINY, CLOUDY. A method guess(WeatherEnum) can accept these values. If the remote service later returns SNOWY, which is not defined locally, deserialization fails.

Brian's Answer

Enums enumerate all known values. As a library provider, you decide which values are allowed, making enums a safe guarantee for inputs.

When used as return values, the provider decides the set, and you may receive unknown values after an upgrade, leading to a high chance of exceptions if you haven't read every detail of the specification.