Подход "API First"

Частично про этот подход я уже рассказал в прошлом посте, сейчас сформулирую более подробно.

Такой подход заключается в том, чтобы перед началом разработки "основной" функциональности - спроектировать API и, возможно, сразу его опубликовать, чтобы им могли пользоваться фронтенд разработчики и все потребители сервиса. Но как минимум спроектировать.

Это позволяет решить целый ворох проблем, связанный с простоями отдельный членов команды или даже разных команд в целом, если они не могут приступать к своей части работ до тех пор, пока им не предоставят описание контракта сервиса, с которым им необходимо взаимодействовать. Особенно это актуально в распределенных командах, тесно взаимодействующих друг с другом.

Не раз и не два у меня было так, что тебе уже нужно приступать к аналитике задачи и проектировать интеграционное взаимодействие с какой-либо системой, а ты не можешь это делать, потому что на той стороне еще ничего нет, и ты даже не представляешь, какие тебе данные нужно будет отдать на вход и что ты получишь на выход. Это достаточно омрачает существование в рамках таких процессов.

Как процесс выглядит на практике со стороны аналитика, проектирующего сервис, у которого будут какие-либо внешние потребители:

➖ Задача поступает тебе в работу, собраны предварительные требования (или даже написано БТ);
➖ Тебе необходимо спроектировать какой-нибудь core-сервис со сложной внутренней логикой, который будет рассчитывать данные для потребителей. У тебя уже есть верхнеуровневое понимание того, какие данные этот сервис будет потреблять и какие данные он будет отдавать на выход;
➖ Вместо того, чтобы начать анализировать саму логику, по которой эти сложные вычисления будут производиться, ты первым делом идешь и накидываешь контракт сервиса в формате черновика, который отдаешь тем командам, которые от тебя зависят на согласование;
➖ Пока контракт выравнивается и происходит обработка замечаний\комментариев ты уже приступаешь к описанию основной логики. При этом ты освободил руки для СА смежных команд, которые уже могут приступать к анализу со своей стороны.
➖ К концу анализа у тебя есть описанный и согласованный контракт, все команды находятся в одинаковом понимании и ожиданиях.

Конечно, это достаточно идеализированный сценарий, потому что и в этом процессе может много что пойти не так. Банально - сначала вы все дружно согласовали контракт, потом у потребителей спустя N времени возникли потребности в каких-то изменениях, без которых они не могут существовать и выполнять свою функцию.

Кроме того, что данный подход может использоваться при кросс-командом взаимодействии - он успешно применяется и внутри команды. Аналитик также проектирует API сервиса до начала разработки, чтобы убедиться в том, что он удовлетворяет требуемой функциональности и всем требованиям. При этом, конечно, разработчики могут давать обратную связь по контракту, подсвечивая недочеты или предлагая варианты по улучшению контракта, чтобы он лучше соответствовал best practices, принятым на проекте.

P.S. Пока писал, подумал, что для меня это уже настолько привычно, что будто бы даже рассказывать смысла не имеет. Но потом вспомнил, что знаю очень много примеров того, когда аналитики в целом не занимаются проектированием сервисов и эта функция целиком лежит на разработчиках.

А на ваших проектах как принято - кто является источником правды с точки зрения проектирования сервисов: аналитик или разработчик?