Api complete

Here's the complete API covered with examples.
If you decide to merge this in master, you'll break things for those who already use your gem. (incompatible API) and should [version accordingly](http://semver.org/).