After building out dozen of API's I have came to conclusion that in order to design a great API you have to start with writing a client for it first.