Разработка REST Api кажется простым делом - перекладывай json-чики с места на место и все дела. Но когда ты сталкиваешься с плохо спроектированными Api-шками и начинаешь задумываться о том, как спроектировать хорошо, тут то и открывается бездна. Особенно интересно то, что каждый знает "как правильно проектировать Api" и часто даже в небольшой команде начинаются жаркие споры и каждый тянет одеяло на себя. Вот еще одна из миллиона статей на тему "как делать правильно", которая мне понравилась взвешенным подходом и подробной аргументацией к каждому пункту. Если вы работаете на проектах, где нет внутреннего стандарта на Api, то рекомендую почитать https://github.com/stickfigure/blog/wiki/How-to-(and-how-not-to)-design-REST-APIs