Rewrote readme and improve api

I would need rubber duck debugging for the only test failing please :(
I can't see why it never receives a response :|
While I love explaining this technique, I believe this should be done with some more explanations.

In this section, we're mixing the definition of the tokens with how to share them (with the hash in the URL). I believe this should be a sub-section.