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 :|
Here, in case we do a PUT request, we don't create it, we update it, so the naming is a bit odd. Not sure how to make that clearer though.