proposed API and deprecations if merged