documentation update

hi yeehaa, please find the api design in the pull request