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 :|
I generally find that our examples in the tests lack a proper use case in mind. reading "abc" and "xyz" doesn't bring much here and doesn't ease the general understanding.