code cleanup, bug fixes, & trying to establish idiomatic formulation of API methods