I wrote this about a year ago for an intro to how I think you should design APIs based on my time at Twilio: http://john-sheehan.com/post/18688963163/dont-build-the-best... Hopefully it helps.