Readme Driven API changes

pinging @kenichi @davy @jwieringa @brooksjbr @poeks for input on this new API