Future-Proofing Java: The Art of Crafting Resilient APIs by Steve Poole

Use proper types instead of primitives - avoid raw types and use enums/objects that represent the actual domain concepts

Consider streams instead of returning collections/arrays - they are more flexible, memory efficient and allow for better filtering/mapping

Leverage sealed classes and interfaces (Java 15+) to control API implementation and prevent unwanted extensions

Use builder pattern for complex APIs instead of constructors - provides more flexibility and cleaner evolution path

Be aware of different validation levels (IDE vs compile-time vs runtime) as they enforce different rules

Design APIs as policy rather than process - separate the what from the how

Pay attention to method signatures, access levels and return types - changing these will break compatibility

Don’t rely solely on semantic versioning - version numbers don’t guarantee compatibility

Have proper testing strategies between versions to catch breaking changes

Use generics carefully and be aware of type erasure implications at runtime

Consider immutability when returning collections

Use records and interfaces to create cleaner API designs

Avoid exposing implementation details through public APIs

Design for evolution by hiding complexity in builders and providing clear extension points