Lib api proposal

Merged proposed API changes onto master.