sensibly update api to decorate, rather than invoke, the orginal function