extending the api to be more strict and explicit

also more consistent behaviour in terms of memory management