update readme and docs with api changes

cc @cpcloud @chdoig 

Pretty minor PR.  Merging soon if no comment.