improve docs, ensure that all api methods return deferred promises with consistent behavior