Я думаю, что вы не раз уже гуглили, заглядывали в статьи, манифесты IT-гигантов о лучших практиках проектирования API. Я тоже.
Но в большинстве из них всё ограничивается описанием URL ресурса, мотивацией использовать пагинацию, сложными словами про кэширование и SSL. Это, безусловно, необходимо для общего понимания технологий, но практически не помогает, когда ты сидишь перед пустой страницей и надо начать “проектировать контракт”.
Я работаю тимлидом направления системного анализа в X5Tech и за все время развития карьеры сталкивалась с большим количеством кейсов проектирования Web систем. IT продукты в большинстве очень динамичны: постоянно изменяются требования, появляются новые, итеративно улучшается пользовательский опыт (по принципу 20% усилий на 80% результата, а остальное доделаем потом).
Часто при проектировании мне помогала следующая идея: было бы здорово проектировать контракт так, чтобы при малейшем изменении/добавлении бизнес-правил его не приходилось сильно трансформировать, так как API является стыковочным звеном между разными слоями приложения. По ходу повествования я приведу пару примеров, чтобы проиллюстрировать такие изменения.
В этой статье предлагаю спроектировать контракт по шагам, и на каждом из них я расскажу про общие рекомендации из копилочки “Полезное”, а также про личные правила и практики, полученные долгим опытом работы над постоянно меняющимися ИТ-продуктами, которые помогут для “дальновидного” проектирования GET REST API.