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 :|
(At least I tend to do that, see https://english.stackexchange.com/questions/78886/she-he-to-refer-a-user)