Очень интересная статья про то как надо проектировать API.