refactored API for improved encapsulation and clarity