Как передать на бекенд требования к API?

Question

[Антон Бреславский]

У нас в команде есть вопрос относительно рабочего процесса по разработке API.

Дизайнер нарисовал экраны и собрал прототип приложения.
Клиент сказал - погнали!

Что дальше? Кто должен начать разрабатывать API: фронтенд или бекенд?

Логичнее всего, фронтенд разработчики лучшего всего понимают какие данные и откуда нужно вывести в дизайне. Конечно, есть Open API и Swagger которые прекрасно работают на небольших проектах. И вопрос, не в том, что Swagger плох, а его просто не удобно редактировать и поддерживать в будущем.

Сейчас фронты делают отдельный GIT репозитарий, где пишут Swagger через YAML, разбивают все по файлам, потом мы добавляем это в CI и в итоге требования к API публикуются на https://spec-api.project.com Ребята из бэка видят требования отсюда, но поддерживать в будущем такую спецификацию становится сложнее. Что бы что-то поменять: нужно перейти в репозитарий, закомиттить, дождаться CI и т.д.

Кто-нибудь видел Swagger в стиле Google Docs или Notion с доступом по ссылке?

Так же к Swagger хотелось бы фичу по привязке областей дизайна к API. Типа выделил область и сказал, тут вызывается /cities?q= и главное, всегда известно какие ендпойнты в какой части приложения дергаются.

Гипотеза: если фронты хорошо знают REST, то это реальный профит, когда они сами могут накидать в Swagger ендпойнтов, которые потом утвердит или поправит бекенд. Если добавить сюда удобный редактор в стиле Notion когда тутже правим и видим превью ендпойинта. А если еще к нему зацепить Swagger с реализованного бэка потом и эта чтука сделает кросс-валидацию и скажет где контракт нарушен - то вообще огонь или нет?

Накидали небольшой скетч идеи. Что скажите? Может быть полезно?

Comments

[Антон Бреславский]

TheAndrey7, так в начале еще нет реализации. Сначала нужно сказать беку что делать. Потом конечно swagger появиться на беке который будет генерироваться из кода. Вопрос, то как передать требования на беке в самом начале, когда дизайн готов и пора проектировать API. Или в вашем случае бек сам смотрит в дизайн и делает API сразу?

[Антон Бреславский]

Agent Smith вы и правда удалили все свои комментарии? Что серьезно?

[Jacen11]

Антон Бреславский,

Кто должен начать разрабатывать API

аналитик

Swagger которые прекрасно работают на небольших проектах

он прекрасно работает и на проектах масштаб которых ты плохо себе представляешь

его просто не удобно редактировать и поддерживать в будущем

что именно сложно? из видов ведения документации самый удобный и простой

Сейчас фронты делают отдельный GIT репозитарий, где пишут Swagger через YAML, разбивают все по файлам, потом мы добавляем это в CI и в итоге требования к API публикуются

бред какой то

бы что-то поменять: нужно перейти в репозитарий, закомиттить, дождаться CI и т.д.

да, вот из за этого и бред

Может быть полезно?

не особо, или надо как то по хитрому продумать. На одном экране может быть куча полей с разными ручками

Сейчас фронты делают отдельный GIT репозитарий, где пишут Swagger через YAML

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

[Антон Бреславский]

Swagger которые прекрасно работают на небольших проектах
он прекрасно работает и на проектах масштаб которых ты плохо себе представляешь

Тут имелось в виде описание Swagger в виде YAML, вы точно поняли суть вопроса? Работали с https://editor.swagger.io/ одним гиганским YAML файлом внутри? Удобно такое потом поддерживать?

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

Тогда Ваш вывод такой: не надо ничего формализовывать, все через чаты, перекинули текст и JSONчики и погнали. Потом проверили ручками, что все сделано правильно.

[Антон Бреславский]

Еще немного информации с https://starkovden.github.io/introduction-openapi-...

Что бы немного успокоить хейтеров.

Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».

Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.

Ну и как проект для совместного создания API спецификаций https://starkovden.github.io/swaggerhub-introducti...

Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.

Видимо те кто хейтил в 15 000 не входят, не обладая информацией, что есть и другой подход.

Верно Agent Smith и за это потом стыдно.

[Everything_is_not_so_bad]

Животрепещущая тема, однако.

[Антон Бреславский]

Роман Мирр, да. Кругом все "профессионалы", а как начинаешь приводить аргументы они или начинают хейтить и откровенно унижать или просто сливаются, так профи не поступают.

[Ярослав Иванов]

Кто должен начать разрабатывать API: фронтенд или бекенд?

Бэк конечно же.

А во-вторых проект начинают с бэка там же и апи.

Кто сначало делает кузов авто а потом двигатель по него? Понятно что ограничить надо в размерах но двигатель в приоритете.

Поэтому апи потом уже корректируетя.

P. S. Фронт это вершина айсберга. Дальше думаю понятно.

[Антон Бреславский]

Ярослав Иванов, спасибо за ответ, что вы можете сказать по поводу этого?

Информация с https://starkovden.github.io/introduction-openapi-...

Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».

Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.

Ну и как проект для совместного создания API спецификаций https://starkovden.github.io/swaggerhub-introducti...

Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.

Если, Вы не делали никогда по другому, не значит что этого нет.

[Ярослав Иванов]

Антон Бреславский,

Если, Вы не делали никогда по другому, не значит что этого нет.

А зачем мне что-то другое?) есть опыт и понимание. Не один продукт такой сделали в разных компаниях)

Звучит предвзято не смотря на то, что вопрос задаете Вы)

P.S. Кто-то верстает сначала под телефоны а потом "наращивает" до больших экранов. Mobile first этот процесс именуют эти граджане. Мало ли сколько у нас психически нездоровых людей в разработке)))

Answer 1

[slapshin]

Мы своей команде используем такой подход: отрисовывается дизайн, фронтендеры анализируют его, решают какие api им нужны для реализации указанного UI, затем кидают задачи на бэк. Бэкенд смотрит предложеный API, если что-то не нравится - общаемся. В принципе, такой подход нас устраивает: фронты пилят UI, бэкэнд реализует бизнес логику, модель данных, занимается оптимизациями производительности и т.д. До этого бэк сам лез в дизайн и продумывал все за фронтов - было не всегда удобно: все таки UI это больше фронтовская тема

Comments

[raiboon]

Какой-то выверт, но возможно, если работаете в веб-студии и делаете относительно простые сайты, имеет место.
Обычно все-таки разработка идет в обратном направлении.

[Антон Бреславский]

raiboon, спасибо за ответ. А почему? API - это по сути просто запрос данных с бекенда. Бизнес слой на беке отдельно, какая разница какой интерфейс? Может быть одновременно и REST и GraphQL, а дергать одну и ту же часть бизнес-логики?

[slapshin]

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

Answer 2

[Vitsliputsli]

Многие фронтендеры относятся к беку, как к некой обертке для работы с базой данной. Когда такие становится лидом команды и начинают диктовать свои требования беку, начинается ад, проект даже с простым беком превращается в нечто монструозное, разваливающиеся на ходу. Но, так как снаружи бек не виден, руководство считает, что дело в отдельных тупых бек-разработчиках, которые артачатся, не хотят работать и увольняются.
Судя по вашим фразам, вы скорее всего один из них. Так как уверены, что приложение - это то, что на фронте, что api - это хрень, которая завязана на отображении информации на фронте, что разработчики бека не нужны при разработке архитектуры и вообще пофиг, что они там делают, главное чтобы давали то, что хочет фронт.
Но, раз вопрос задан, значит сомнения вас посещают. Поэтому: приложение это не только фронт, а зачастую фронт это не самая сложная его часть. Бек - это не обертка над базой данных, и если вы поменяете значение в базе, это не значит, что к примеру, в потоковом вещании сменится кодек (вот, кому-то может и смешно, а мне в такой ситуации ни фига не было весело). С помощью API получают данные, поэтому не важно, что там у вас напроектировали дизайнеры, или как эти данные выводит фронт, API должен быть универсальным и не зависить от того как вы отображаете данные, поэтому, к примеру, бек может вам дать для получения данных несколько универсальных запросов, а не один специальный. В общем, все гораздо сложнее, и ваш вопрос как состыковать фронт и бек перерастает в вопрос как формировать архитектуру проекта, и как управлять командой.

Comments

[Антон Бреславский]

Спасибо большое за ответ. Но обязательно переходить на личности?

Судя по вашим фразам, Вы скорее всего один из них.

Это такой формат общения: унизить и оскорбить прежде, чем ответить? Не важно какой у меня опыт 5 или 15 лет. Если Вы бекенд разработчик, значит у Вас предвзятое отношение к фронту или Вы работали только с плохими фронтент разработчиками и у вас какая-то обида на них? Они вас не ценили?

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

Вопрос не в том, что фронтенд проектирует API и делает это всегда плохо, а в том, что может предложить как и какие данные он хочет получить от бэка. Для этого и есть Swagger в YAML. Если бэкенд видит это по другому, они тут же внесут изменения в спеку, но у них будет готовый контракт, что бы работать параллельно: один на моках, другой с реальной базой, так нельзя делать? Или это не оптимально?

[Vitsliputsli]

Антон Бреславский, поэтому и пишу "скорее всего" и многие, а не все. Дело не в унижении или оскорблении, если ваше восприятие совпадает, с описанном выше, то следует срочно его пересмотреть, т.к. здесь дело даже не в том, что что-то не знаешь или неправильно видишь, все мы что-то не знаем и где-то ошибаемся, а в том, что координально не правильно воспринимаешь и не знаешь базисных принципов, это катастрофично для проекта. Если выше написанное не про вас, не воспринимайте на свой счет, если что-то зацепило - то стоит задуматься.
Вы правильно здесь пишите, но теперь перенесите это и на бек тоже, именно про это я писал, нисколько не умаляя сложностей фронтенд разработки, я остерегал от поверхностного отношения к беку. Огромный - это нисколько не показатель сложности для запроса в базу. Возможно у вас, действительно, на беке нет ничего сложного, а только запросы к бд, но даже в этом случае, нужно пересмотреть отношение к API, иначе это будет не интерфейс взаимодействия независимых сервисов, а прослойка, которая увеличит зацепленность и многократно усложнит их взаимодействие. Поэтому вопрос не в том, что "фронтенд проектирует API и делает это всегда плохо", а в том, что по вашему описанию, вы сейчас руководствуетесь неправильными принципами подходя к проектированию API, это и есть проблема. И речь не про swagger и yaml, или моки, или что фронт и бек умеют договариваться, тут все верно, но если бы все так и было, то не было бы и вопроса.

[Антон Бреславский]

Если выше написанное не про вас, не воспринимайте на свой счет, если что-то зацепило - то стоит задуматься.

Это очень удобная позиция :-) Вы скорее всего *** и если Вас это зацепило, то это Вы :-)

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

Мне кажется проблема в том, что плохие бекенд разработчики не верно понимают разработку бизнес-логики и разработку интерфейса доступа к ней и к данным. Интерфейс на бекенд может быть HTTP, сокеты ли даже командная строка. Это всего лишь интерфейс. Эти разработчики при проектировании ендпойнта /login часто зашивают в контроллер бизнес-логику, работу с базой, генерацию сессии и т.д. И именно поэтому они связывают проектирование API с разработкой кода функции и именно поэтому когда им нужно добавить например GraphQL им нужно дублировать функционал.

Почему заранее нельзя договориться с фронтом как данные будут бегать туда-обратно и начать работу параллельно? Такого кейса нет? Фронты не могут предложить вариант как это видят? Вы на беке дадите добро или внесете изменения и у вас будет контракт с фронтами. Вы спокойно пойдете делать и они тоже. Потом через какое-то время вы соединитесь и проверите, что ваш контракт выполнен. Что тут не так?

[Vitsliputsli]

Антон Бреславский, да ничего удобного, просто отметил, на тот случай, если не правильно трактовал фразы, но раз спорите не с ними - значит можете вычеркнуть "скорее всего".
Разработка API связана с проектированием передачи сущностей и контроля их взаимодействия. Так как бизнес-логика находится на беке, то создаются эти сущности в первую очередь на беке, в какие сущности они будут переданы на фронте и как отображены - вопрос вторичный. Поэтому проектирование API без бека - это мягко говоря странно. А то, что кто-то не знает, что такое mvc, это печально, но к делу не относится.
И вы зря так про интерфейсы, "HTTP, сокеты ли даже командная строка" - это не "всего лишь интерфейсы", это разные архитектурные подходы, воплощающие разное взаимодействие, поэтому чаще всего они будут использованы для разной бизнес-логики. Да, есть такой момент, когда при невозможности соединиться по ws используют костыль - sse или long-polling, но это частный случай.
Просто подумайте:
http - клиент-серверные заросы в сторону сервера, подразумевающее обработку разными процессами, как правило независимые.
cli - работа app по параметрам или интерактивное, подразумевающее запросы от сервера.
ws - клиент-серверное взаимодействие в обе стороны.
Т.е. в зависимости от архитектурных требований, будет использоваться разный подход.

Почему заранее нельзя договориться с фронтом как данные будут бегать туда-обратно и начать работу параллельно?

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

[Антон Бреславский]

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

Vitsliputsli, у меня где-то написано про такую позицию? Если описание DTO на фронтенл для API вызывает такую реакцию, то у бекенд разработчика проблемы с самооценкой наверное.

В качестве вывода, в Вашем случае фронт все таки не могут предлагать контракт взаимодействия с беком путем написания его в Swagger со последующим обсуждением и правками с бэком?

[Vitsliputsli]

Антон Бреславский,

у меня где-то написано про такую позицию? Если описание DTO на фронтенл для API вызывает такую реакцию, то у бекенд разработчика проблемы с самооценкой наверное.

я вот про этот комментарий на ответ AgentSmith:

То есть в Вашем случае, мы должны ставить задачи беку и прикладывать к ним картинки? По этим картинкам они уже создают API? Фронты пока сидят и ждут когда бэк что-то уже сделает? Получает бек должен хорошо разбираться в дизайне, понимать как работает приложение и т.д. Верно?

Что api создаются по картинкам, и если их отдать беку, то что они могут хорошего сделать, если не понимают как работает приложение, т.е. картинки. Только не говорите, что это AgentSmith придумал, что api создаются по картинкам. Вообще, эпичный комментарий, ничем не хуже того, что я про базу писал в ответе.

И какой, нафиг, DTO, если по вашему мировозрению вы его из картинок должны составлять?

Хотя, то что на ходу переобуваетесь, значит все что мы тут пишем не прошло даром, и вы что-то начали понимать, вон уже и DTO вспомнили.

В качестве вывода, в Вашем случае фронт все таки не могут предлагать контракт взаимодействия с беком путем написания его в Swagger со последующим обсуждением и правками с бэком?

Неа, раза 3 уже написал, что я не про это говорю, так как проблема не в этом.

[Антон Бреславский]

Что api создаются по картинкам, и если их отдать беку, то что они могут хорошего сделать, если не понимают как работает приложение, т.е. картинки. Только не говорите, что это AgentSmith придумал, что api создаются по картинкам. Вообще, эпичный комментарий, ничем не хуже того, что я про базу писал в ответе.

Возможно, выглядит эпично. Но если у меня на картинке (окей, экране интерфейса) список пользователей, я не могу спроектировать к этой области API вместе с DTO (модель, схема данных)? Я же вижу какие столбцы в таблице, есть пейджинг, есть поиск. Отправлю на бэк Swagger, бэк скажет, да мы можем реализовать это так. Мокай. Что тут плохого? Вся суть вопроса только в этом, не заменить бэк, не отнять у них работу, а оперативно согласовывать API и не ждать когда они выльют.

[Антон Бреславский]

Vitsliputsli, и мой комментарий был такой

То есть в Вашем случае, мы должны ставить задачи беку и прикладывать к ним картинки? По этим картинкам они уже создают API? Фронты пока сидят и ждут когда бэк что-то уже сделает? Получает бек должен хорошо разбираться в дизайне, понимать как работает приложение и т.д. Верно?

Тут не было оценок, вставка

и если их отдать беку, то что они могут хорошего сделать, если не понимают как работает приложение, т.е. картинки.

Это ваша личная оценка, у меня это был как вопрос

Получает бек должен хорошо разбираться в дизайне, понимать как работает приложение и т.д. Верно?

Поэтому оценка, что бекенд не может, ваш вывод.

[Vitsliputsli]

Антон Бреславский,

Вся суть вопроса только в этом, не заменить бэк, не отнять у них работу, а оперативно согласовывать API

В 4ый раз, в согласовании ничего плохого нет.

Но если у меня на картинке (окей, экране интерфейса) список пользователей, я не могу спроектировать к этой области API вместе с DTO (модель, схема данных)?

Можете. 2ой раз, бизнес логика на беке, сущности в первую очередь создаются там, их взаимодействие тоже, отображение вторично, но можете сделать наоборот.

Это ваша личная оценка, у меня это был как вопрос
"Получает бек должен хорошо разбираться в дизайне, понимать как работает приложение и т.д. Верно?"
Поэтому оценка, что бекенд не может, ваш вывод.

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

[Антон Бреславский]

Vitsliputsli, так получается мое предложение рабочее и ничего токсичного в нем нет? В чем тогда проблема? В чем такой негатив? Я на фронт прошу только данные прислать в таком формате, у вас там свои модели, но DTO у нас общее.

[Vitsliputsli]

Антон Бреславский, ни проблем, ни негатива. Лишь описание ситуаций, принимать решения вам, нести за них ответственность тоже.
Как опять от согласования перешли к "Но если у меня на картинке (окей, экране интерфейса) список пользователей, я не могу спроектировать к этой области API вместе с DTO (модель, схема данных)?" я не понял.
И если ничего не смущает в фразе: "бизнес логика на беке, сущности в первую очередь создаются там, их взаимодействие тоже, отображение вторично, но можете сделать наоборот", то вам с этим разбираться.
У меня новых аргументов не будет.

[Антон Бреславский]

Антон Бреславский, ни проблем, ни негатива. Лишь описание ситуаций, принимать решения вам, нести за них ответственность тоже.

Так в комментах, как раз таки именно оценки, пример я уже приводил.

Но если у меня на картинке (окей, экране интерфейса) список пользователей, я не могу спроектировать к этой области API вместе с DTO (модель, схема данных)?

Вот пример инструмента на простом примере, что тут не понятного?

.

Есть картинка, с нее описали вызовы к API.

Бизнес логика на беке, сущности в первую очередь создаются там, их взаимодействие тоже, отображение вторично, но можете сделать наоборот

Это вывод чистого бекенщика. Бэк все - фронт ничто. Но если бекенщик в одну кучу сваливает модели бизнез-логики, их взаимодействие в бизнес слое и выдачу их во внешний мир - в один слой, тогда да конечно API для него = весь бэкенд и считает, что фронты решили его убрать :-)

[Alex Wells]

Антон Бреславский, да, есть картинка, описали с нее вызовы к АПИ. Аж две проблемы:
1) что если на картинке будет не форма из трех полей, а сложная длинная форма с пару десяткой полей? Впихнете все в POST /register? А в результате бэкэнд спроектирует это так, что вы сможете контроллировать каждую сущность по отдельности, и вам прийдется переписывать всю вашу логику с одного запроса на десяток. И какой тогда смысл от вашей работы, вашего проэктирования и ваших моков, если все надо переделывать?

Или вы считаете, что фронт может в проэктирование сущностей (и, следовательно, эндпоинтов)? Нет, не может, только если у него нет существенного бэкэнд опыта.

2) даже с простецкой картинкой фронтом было бы предложено 5 урлов. А бэк говорит: cities тащи из какого-нибудь google places/geocode API, verify-phone будет PATCH запросом на /users/validate, /register будет POST /users. А так как у юзера может быть два и больше телефонов (хоть ради упрощения и выводится только один на форме), то и для телефонов отдельный CRUD. Немного затянуто за уши, но и пример слишком простой.

И опять все выкидывать, вместе с вашими ДТОшками/интерфейсами, моками, сваггером и прочим.

К чему это я: НЕТ никакого смысла преждевременно проэктировать АПИ фронту, если финальное слово не за ним. Это трата времени в пустую. Лучше занять фронта другими задачами, пока готовится бэкэнд. Не обязательно разрабатывать паралелльно, вот и все.

[Антон Бреславский]

Alex Wells, спасибо за развернутый ответ.

Как вы прокомментируете?

Мне кажется проблема в том, что бекенд разработчики не верно понимают разработку бизнес-логики и разработку интерфейса доступа к ней и к данным. Интерфейс на бекенд может быть HTTP, сокеты ли даже командная строка. Это всего лишь интерфейс. Эти разработчики при проектировании ендпойнта /login часто зашивают в контроллер бизнес-логику, работу с базой, генерацию сессии и т.д. И именно поэтому они связывают проектирование API с разработкой кода функции и именно поэтому когда им нужно добавить например GraphQL им нужно дублировать функционал.

Что скажите? Или API это больше чем данные?

Почему заранее нельзя договориться с фронтом как данные будут бегать туда-обратно и начать работу параллельно? Такого кейса нет? Фронты не могут предложить вариант как это видят? Вы на беке дадите добро или внесете изменения и у вас будет контракт с фронтами. Вы спокойно пойдете делать и они тоже. Потом через какое-то время вы соединитесь и проверите, что ваш контракт выполнен. Что тут не так?

Информация с https://starkovden.github.io/introduction-openapi-...

Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».

Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.

Ну и как проект для совместного создания API спецификаций https://starkovden.github.io/swaggerhub-introducti...

Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.

Если, Вы не делали никогда по другому, не значит что этого нет?
Есть не только фронты, есть архитектор наконец, и 5 фронт разработчиков.
Есть опытные фронт разработчики и менее опытные бэк, такое может быть.

Ну и собственно сам вопрос.

Гипотеза: если фронты хорошо знают REST, то это реальный профит, когда они сами могут накидать в Swagger ендпойнтов, которые потом утвердит или поправит бекенд. Если добавить сюда удобный редактор в стиле Notion когда тутже правим и видим превью ендпойинта. А если еще к нему зацепить Swagger с реализованного бэка потом и эта чтука сделает кросс-валидацию и скажет где контракт нарушен - то вообще огонь или нет?

[Alex Wells]

Антон Бреславский,

Мне кажется проблема в том, что бекенд разработчики не верно понимают разработку бизнес-логики и разработку интерфейса доступа к ней и к данным. Интерфейс на бекенд может быть HTTP, сокеты ли даже командная строка. Это всего лишь интерфейс. Эти разработчики при проектировании ендпойнта /login часто зашивают в контроллер бизнес-логику, работу с базой, генерацию сессии и т.д. И именно поэтому они связывают проектирование API с разработкой кода функции и именно поэтому когда им нужно добавить например GraphQL им нужно дублировать функционал.

Что скажите? Или API это больше чем данные?

Не понял в чем аргумент. Ну, допустим не понимают. Допустим, им потом сложно реализовать GraphQL (хотя сюрприз-сюрприз, из-за его стандартизации разработчики как раз и дублируют функционал, потому что многие вещи существующие либы для него делают автоматически, а это совсем несовместимо с другим кодом не под graph. Ну да ладно).

Допустим они тупят. Смею предположить, что из-за недостатка опыта? Если дело в этом, то я же не говорил, что бэк всегда прав. Я сказал, что финальное слово за ним, даже если они до этого договорились с фронтом. Если дело не в этом, то я не понимаю в чем тогда аргумент.

Почему заранее нельзя договориться с фронтом как данные будут бегать туда-обратно и начать работу параллельно? Такого кейса нет? Фронты не могут предложить вариант как это видят? Вы на беке дадите добро или внесете изменения и у вас будет контракт с фронтами. Вы спокойно пойдете делать и они тоже. Потом через какое-то время вы соединитесь и проверите, что ваш контракт выполнен. Что тут не так?

Это отличный вариант. Обычно и так договариваются наперед, просто без каких-либо тулз. Согласен, с тулзами будет удобней. Но с ними или без важны две вещи:
1) фронт не должен начинать работу, пока не согласовал контракт с бэком
2) не всегда у бэка есть возможность (например, из-за недостатка времени или из-за предвиденых сложностей) это сделать тогда, когда нужно фронту. Опять же, важно, что бы фронт не начал работать в это время

Если, Вы не делали никогда по другому, не значит что этого нет?

Я такого не говорил :)

Есть не только фронты, есть архитектор наконец, и 5 фронт разработчиков.

Ну, речь то была не об архитекторе, а о фронтах. У архитектора есть соответсвующий бэк опыт.

Есть опытные фронт разработчики и менее опытные бэк, такое может быть.

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

Гипотеза: если фронты хорошо знают REST, то это реальный профит, когда они сами могут накидать в Swagger ендпойнтов, которые потом утвердит или поправит бекенд. Если добавить сюда удобный редактор в стиле Notion когда тутже правим и видим превью ендпойинта. А если еще к нему зацепить Swagger с реализованного бэка потом и эта чтука сделает кросс-валидацию и скажет где контракт нарушен - то вообще огонь или нет?

Опять же, все дело в опыте и вероятности. Если фича простая - конечно, им не составит труда спроэктировать сущности и, следовательно, эндпоинты. А вот если она чуть сложнее, то тут нужно будет не знание REST, а опыт с сущностями, которого у фронта нет или очень мало. Поэтому вероятность правильного проэктирования АПИ фронтом, имхо, не слишком высока.

Но да, в целом это вариант, особенно если на фронте опытные ребята.

[Антон Бреславский]

Alex Wells, спасибо, это вариант и называется Spec-First :-)

По идее схема такая: Фронты ↔ API контракт API ↔ Бекенд: бизнес-логика, база, кэш и т.д.

И если API это просто язык общения, тогда не вижу проблемы выучить его обоим сторонам и согласовывать до реализации. Просто выучи язык и всем будет профит.

К чему это я: НЕТ никакого смысла преждевременно проэктировать АПИ фронту, если финальное слово не за ним. Это трата времени в пустую.

Не понимаю, почему не за ним :-) Оно за всеми, в данном контракте 2 стороны.
Если бэк сделает в API, то, что не нужно фронтам, нафиг такой бэк? Нафиг вообще API? Он кроме фронтов пользователю вообще не нужен. Поэтому заказчиком для бэка выступает фронт, который и заключает с бэком контракт через YAML OpenAPI, а потом через кросс-валюдацию проверяет, что контракт исполнен. По-моему очень формализованный и четкий подход. А не из серии: бэк - я так вижу, да будет так, вот вам 1000 полей в пользователе, пофиг что выводить 5 только лишь, а лишние байты зачем?

[Alex Wells]

Антон Бреславский,

Не понимаю, почему не за ним :-) Оно за всеми, в данном контракте 2 стороны.

Потому что как я сказал выше, почти всегда более сильная сторона в проэктировании сущностей - бэк. У него тупо больше опыта в этом, потому что это то, с чем он работает постоянно, в отличии от фронта.

Если бэк сделает в API, то, что не нужно фронтам, нафиг такой бэк?

И в этом часть проблемы. Многие фронты не понимают, что АПИ делают не для них. АПИ делают что бы с приложением (бэкэнд) можно было общаться какими либо методами, а не для фронта/мобайла. АПИ делают таким, что бы с ним мог работать не только фронт, но и какие-нибудь сторонние боты, скрипты, интегрироваться другие системы.

И что бы не плодить эндпоинтов, код, усложнять логику и траблшутинг - АПИ делают универсальным. Да, фронту бывает работать с этим неудобно, особенно если брать в рассчет только одну небольшую фичу. Зато допиливать потом ничего не нужно, когда фронт поменяется, компанию купят для интеграции, откроют публичное АПИ, фичу допилят или переделают и тд.

Так что АПИ не для фронта. Точнее, не только для фронта, даже если других консюмеров на данный момент нет :)

А не из серии: бэк - я так вижу, да будет так, вот вам 1000 полей в пользователе, пофиг что выводить 5 только лишь, а лишние байты зачем?

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

Answer 3

[キム ファイブプラス]

Судя по описанию у вас команда в целом не понимает что делать и как. А то что делают, делают неправильно.
Стоит начать с того, чтобы найти хорошего лида. Тогда все вопросы о том, кто и что должен делать, и в какой последовательности отпадут сами собой.

Comments

[Антон Бреславский]

Спасибо за очень не конструктивный ответ и помощь в оценке моей компетенции. Имеет место быть :-)
Какая, не какая помощь :-)

[キム ファイブプラス]

Антон Бреславский, Какой вопрос, такой и ответ. Пользуйтесь на здоровье)

[Николай Савельев]

Антон Бреславский, судя по вопросу ты некомпетентен и лидом ты назвал себя сам.
Подтвердить свою компетенцию на должность лида ты не можешь

[Антон Бреславский]

Agent Smith, а зачем все удалять? Значит стыдно что ли? Теперь конечно, уже не ничего не подтвердишь, когда целая ветка удалена :-) Ну хорошо, что Вам стыдно стало, значит еще не все потеряно. По-сути своим поступком, Вы как раз таки подтвердили свою неадекватность.

Answer 4

[Aetae]

API разрабатывает бэк, но не по дизайну, а по аналитике от ТЗ.
Если есть только дизайн, то всё равно надо посадить аналитика который по пунктам распишет весь функционал. Иначе будет сказка про лебедя, рака и щуку. Страшная.

Далее разработка выглядит примерно так:

Параллельно:
Фронт начинает пилить визуальную часть без привязки к бэку.
Бэк исходя из аналитики думает архитектуру и кидает примерный json(а не точный свагер, лишняя трата времени).

Совместно:
Фронт смотрит этот json и если видит, что чего-то не хватает - запускает обсуждение с бэком.

Параллельно:
Бэк пилит по очереди сервисы\эндпоинты с автогенерацией свагера из кода.
Фронт пилит на основе простых json-моков из предыдущего шага и по готовности подключает эндпоинты с автогенерацией клиента из свагера.

Заранее руками разрабатывать свагер - это абсолютно бессмысленно. Требования всегда меняются на лету, а свагер достаточно сложен, чтоб потратить много лишних часов на мартышкин труд.

P.S. Привязывать API к UI - безумие. UI - это мимолётная штука, как сумочка у дамы. Сегодня одна, завтра другая. API же опирается на архитектуру приложения, от которой зависит всё: и бизнес-логика, и тупо скорость работы, и многое другое.

Comments

[Антон Бреславский]

Спасибо за конструктивный ответ! То есть бекенд тратит время, что бы накидать примерный JSON и описание ендпойнтов в тексте, а фронт потом тратит время что бы это, если что поправить и переслать?

Что если они кинут ссылку на спеку и в реальном времени будут накидывать и править Swagger - их будущий контракт? Потом на беке появиться реальный сваггер и мы сможем сматчить его со спецификацией? Всегда поймем, что пропущено, всегда сможем что-то добавить? Не в тексте в тасках, а в спецификации?

Например вот так

[Aetae]

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

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

[Антон Бреславский]

Aetae, получается вариант, когда из сваггера генерируется сервер нереален? В этом случае нет повторения работы.

[Aetae]

Антон Бреславский, не, абсолютно нереален.)
На клиенте из сваггера генерируется просто запросы, а на бэке вы что собрались генерировать? Методы класса? Которые потом бэк должен как-то "заполнить кодом", чтоб оно работало?)

[Антон Бреславский]

Aetae, каркас кода и DTO. Но главное, даже не это. Если, они заранее не договорятся, каждый будет писать свое. Писать JSON или Swagger - получается только вопрос удобства?

[Everything_is_not_so_bad]

Антон Бреславский,
бэк лучше всего начать с достаточного понимания потока данных (data flow). Как только будут понятны механизмы получения данных от пользователя, преобразований, сохранения в БД и передачи получателю, можно начать строить блоки и модели данных.

[Aetae]

Антон Бреславский,

каркас кода и DTO.

Абсолютно бессмысленный. Невозможно придумать (адекватно) архитектуру от API, а не от задачи.

Писать JSON или Swagger - получается только вопрос удобства?

Коротко: да.
Развёрнуто: если б меня лично заставили писать свагер руками я б послал тимлида нафиг. Если настаивали - уволился. Не переношу мартышкин труд. То что может быть автоматизировано - должно быть автоматизировано.
Потенциальная "потеря времени" на мелкие правки и нестыковки простых json-моков, как по мне, куда меньше, чем потеря времени на ручную работу со свагером.
Допускаю, что есть какие-то мега-сложные задачи с мега-сложны API где это было бы оправдано, но я такого не встречал.

[Антон Бреславский]

Роман Мирр, спасибо, а разве не понятно что там дизайнер нарисовал? Дизайнер тоже ведь с проджект-менеджером это делал. Есть таблица, в дизайне, сразу понятно, что туда вывести или нет?

[Антон Бреславский]

Aetae, тогда вопрос только удобства. Если Вам дадут супер удобный редактор, чисто гипотетически Вы бы писали?

[Aetae]

Антон Бреславский, про дизайнера - нет. Ни фига не понятно, что он там нарисовал и какая там логика кроется за каждой кнопкой.

Без ТЗ - результат ХЗ.

Про редактор - врядли. Я не верю, что он будет удобным. Просто не вижу вариантов. Если вдруг - то вдруг, но не тыкая руками тут ничего не скажешь.

[Антон Бреславский]

про дизайнера - нет. Ни фига не понятно, что он там нарисовал и какая там логика кроется за каждой кнопкой.

У фронтов больше опыта понять, что там вывести в дизайне. Они накидают сами Вам Swagger на бек, вы посмотрите и поправите с чем не согласны и у них с вами контракт. Не бэк просят писать сваггер, их просят посмотреть требования в сваггере и согласовать их.

[Aetae]

Антон Бреславский, я фронт, мне нифига не понятно что там дизайнер нарисовал.)
За каждой кнопкой и формочкой скрывается логика. Которая должна быть расписана аналитиком без разночтений.
Это верно для чего угодно сложнее лендинга.

Бэк делает логику. Не api - логику. Api - следствие логики и архитектуры, не наоборот. Сколько раз вам ещё повторить?

[Антон Бреславский]

Aetae, а прототип? :) То есть получается бэк лучше поймет как данные из его API сматчить с дизайном?

[Aetae]

Антон Бреславский, что вы упёрлись в этот дизайн? Дизайн решает задачу, фронт решает задачу, бэк решает задачу. Это всё производное от ЗАДАЧИ. И бэк делает ядро: бизнес логика, хранение, производительность и т.д. и т.п. От бэка зависит всё остальное. Да, даже дизайнеру придётся свой креатив перерисовать, если что-то сделать на бэке по той или иной причине невозможно.

Смапить предоставленный бэком API на дизайн - задача фронта. Если дизайн не расходится с поставленной задачей - API будет подходящим. Если чего-то (удобного в конкретном кейсе) не хватает - задача фронта обсудить это с бэком, я не зря включил этот пункт в ответ.

А для прототипа достаточно интерактивной фигмы.)

[Антон Бреславский]

Aetae, получается формализовать работу никак и фронты вынуждены ждать когда появиться бэк, ну или просить их JSONчики хотя бы пока на время прислать?

[Aetae]

Антон Бреславский, у фронта есть дофига чего пилить без бэка. Пока они это напилят - бэк обычно успевает подъехать.)

А формализовать можно, только это выльется в тысячу митингов и пересогласований, пока не устаканится в действительно рабочем варианте. Потому что бэк всё равно так или иначе должен продумать архитектуру, только теперь пытаясь её уродовать, вписывая в бессмысленные требования, взятые с потолка, а не из задачи. Т.е. просто выкидывание времени в трубу и ухудшение конечного результата.

[Антон Бреславский]

Aetae, такой подход :-) Бекенд идеален и потом его как-то нужно выписать в требования от фронта. Ну нарисовано в дизайне и заказчик хочет - разве это с потолка?

[Антон Бреславский]

Aetae, спасибо за Вашу дискуссию, она достаточно предметна.
Разрешите мне еще вставить отрывок из другого моего комментария:

Мне кажется проблема в том, что бекенд разработчики не верно понимают разработку бизнес-логики и разработку интерфейса доступа к ней и к данным. Интерфейс на бекенд может быть HTTP, сокеты ли даже командная строка. Это всего лишь интерфейс. Эти разработчики при проектировании ендпойнта /login часто зашивают в контроллер бизнес-логику, работу с базой, генерацию сессии и т.д. И именно поэтому они связывают проектирование API с разработкой кода функции и именно поэтому когда им нужно добавить например GraphQL им нужно дублировать функционал.

Что скажите? Или API это больше чем данные?

Почему заранее нельзя договориться с фронтом как данные будут бегать туда-обратно и начать работу параллельно? Такого кейса нет? Фронты не могут предложить вариант как это видят? Вы на беке дадите добро или внесете изменения и у вас будет контракт с фронтами. Вы спокойно пойдете делать и они тоже. Потом через какое-то время вы соединитесь и проверите, что ваш контракт выполнен. Что тут не так?

[Aetae]

API это больше чем данные

^this

API это отражение архитектуры. Определённые данные в определённой архитектуре можно получать только определёнными путями.
Утрируя: для фронта это разница меж /get/uuid и /uuid/get, для бэка это полная переделка всего кода или костыль с вытягиванием половины базы на каждый запрос.

Бэк (а точнее Архитектор, но архитектор - всегда как минимум бэк) продумывает архитектуру для оптимального выполнения задачи. От этой архитектуры строится API. Если API не слишком удобно для фронта, но с ним можно жить, это нормально. Если в API не хватает чего-то и это не предусмотрено в архитектуре, но подразумевается задачей - архитектор накосячил и надо всё переделывать(или писать костыли).

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

Вы на беке дадите добро или внесете изменения и у вас будет контракт с фронтами.

Вы не можете дать добро если сами не знаете. А сами вы не знаете пока не готова архитектура соответствующая задаче. А когда готова архитектура - готово и черновое API. Вот тут вы можете дать добро если оно вписывается. Но этот этап уже сильно позднее начала разработки.
Фронты могут высказать пожелания по API до начала разработки архитектуры или во время, но это именно пожелания, никаких строгих контрактов на этом этапе быть не может, потому что хорошая оптимальная архитектура - это не разок затылок почесать.

[Антон Бреславский]

Утрируя: для фронта это разница меж /get/uuid и /uuid/get, для бэка это полная переделка всего кода или костыль с вытягиванием половины базы на каждый запрос.

Не совсем понятный пример, так как для бэка требования к API есть по-сути вход и есть выход.
Если Вам нужно сделать сложную агрегацию: сделайте кэш и берите и кэша с обновлением в 5 мин.

Мне в дизайне нужно вывести, это не мой каприз, а требование заказчика, как это сделает бэк мне какая разница? Будет он каждый раз дергать запрос и 1 000 000 строк или сделает слой.

Опять же, если Ваша архитектура сильно завязана на REST API, значит архитектура плохая.

[Aetae]

Антон Бреславский, что значит требование заказчика? Это требование было в ТЗ, но архитектура не предусмотрела? Косяк архитектора, как я и написал.
Требования не было в ТЗ? Заказчик идёт нахрен или заключает новый договор на много денег, т.к. данное изменение требует переработки архитектуры. Не вижу ничего необычного.

А качество вашей архитектуры зависит от вашего архитектора и к теме не относится. И это не архитектура завязана на REST, а возможный REST завязан на архитектуру. Что-то сделать можно, что-то нельзя. Универсальности не существует.

Будет он каждый раз дергать запрос и 1 000 000 строк или сделает слой.

Я видел такие вещи. Нет, спасибо.
Впрочем - "заказчик хавает", да. До поры. Но нормальный бэк от вас уйдёт.

[Антон Бреславский]

Антон Бреславский, что значит требование заказчика? Это требование было в ТЗ, но архитектура не предусмотрела? Косяк архитектора, как я и написал.
Требования не было в ТЗ? Заказчик идёт нахрен или заключает новый договор на много денег, т.к. данное изменение требует переработки архитектуры. Не вижу ничего необычного.

Я не писал, что его не было. Оно было изначально. И почему фронты не могут написать структуру данных которая им нужна, тоже не понятна для выполнения этого требования в виде вывода виджета?

Будет он каждый раз дергать запрос и 1 000 000 строк или сделает слой.

Не понял подвоха :-) Причем тут заказчик? Есть агрегация сложная, сделай слой и храни в мемкеше.

[Aetae]

Антон Бреславский,

Оно было изначально.

Если оно было - оно было. Duh.
Аналитик должен был описать требуемый функционал.

Есть агрегация сложная, сделай слой и храни в мемкеше.

Если нет хлеба - пусть кушают пирожные.

Вы же понимаете, что подобные заявления заставляют меня склоняться на сторону Agent Smith ?)

[Антон Бреславский]

Aetae, а так вы на бекенде все таки :-)

[Aetae]

Антон Бреславский, сейчас я чистый фронт, и слава ёжикам.
Но я знаю как всё работает со всех сторон.

Answer 5

[Василий Банников]

Кто должен начать разрабатывать API: фронтенд или бекенд?

Совместно, исходя из требований.
Какие данные нужны для бизнес-процесса, и как эти данные будет использовать фронт.
Исходя из этого можно договориться об API.
Реализацией заниматься должны только бэкендеры

Конечно, есть Open API и Swagger которые прекрасно работают на небольших проектах. И вопрос, не в том, что Swagger плох, а его просто не удобно редактировать и поддерживать в будущем.

Большинство фреймворков умеют генерировать OpenAPI спецификацию по исходникам, либо наоборот - реализацию по спецификации.

Кто-нибудь видел Swagger в стиле Google Docs или Notion с доступом по ссылке?

Зачем в стиле гуглодоков, когда есть swaggerUI? А доступ по ссылке можно реализовать буквально в пару строчек.

Так же к Swagger хотелось бы фичу по привязке областей дизайна к API. Типа выделил область и сказал, тут вызывается /cities?q= и главное, всегда известно какие ендпойнты в какой части приложения дергаются.

Накидали небольшой скетч идеи. Что скажите? Может быть полезно?

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

Comments

[Антон Бреславский]

Спасибо за ответ!

Какие данные нужны для бизнес-процесса, и как эти данные будет использовать фронт.
Исходя из этого можно договориться об API.
Реализацией заниматься должны только бэкендеры

А как они у Вас договариваются? Сидят рядом, пишут JSON?

Зачем в стиле гуглодоков, когда есть swaggerUI? А доступ по ссылке можно реализовать буквально в пару строчек.

Спеку хранить в одном YAML god файле? А как его редактировать совместно?

Бэкендеру знать о том, как работает фронт не обязательно.

Верно, ему даже дизайн видеть не нужно, тогда как понять, что нужно сделать? Значит ему должны написать Swagger в любом случае. Как ему его передать? Как потом его актуализировать вместе? Как сравнивать с его Swagger генерируемый из кода?

[Антон Бреславский]

Какие ендпоинты где дёргаются - это фронты и так хорошо знают.

А когда проект большой? Каждый работает над разными фичами. Где им соединиться в одинаковых ендпойнтах? На разных экранах могут дергаться одни и те же ендпойнты. Бэка еще нет, где смотреть, что уже спроектировано для бэка?

[Василий Банников]

Антон Бреславский,

А как они у Вас договариваются? Сидят рядом, пишут JSON?

Обычно примерно так выглядит.
(Бэк что-то придумал)
Б: Эй фронт, тебе вот для этой задачи вот такая апишка подойдёт?
Ф: Вроде ок, да.

Если что-то сложное, то вместе сидим, думаем какие будут параметры, и что будет возвращаться.

[Василий Банников]

Антон Бреславский,

Спеку хранить в одном YAML god файле? А как его редактировать совместно?

Спека очень любит устаревать. Если у вас внутренний API, то проще сразу код генерить.
Если открытый API, то и изменений больших быть не должно.

Верно, ему даже дизайн видеть не нужно, тогда как понять, что нужно сделать? Значит ему должны написать Swagger в любом случае. Как ему его передать? Как потом его актуализировать вместе? Как сравнивать с его Swagger генерируемый из кода?

Не нужно к сваггеру привязываться.

Для отслеживания несделанной работы существуют трекеры задач.

[Антон Бреславский]

Василий Банников, а причем тут бэк придумал? Придумал дизайнер, он придумал картинку, которая понравилась пользователю. Мы отдаем ее бэку и он накидывает код и уже генерит сваггер и говорит фронту, вот для этой картинки такой API?

Если что-то сложное, то вместе сидим, думаем какие будут параметры, и что будет возвращаться.

В результате есть описание на выходе, нейминг полей или считается, что все друг друга поняли?

[Антон Бреславский]

Василий Банников, так все же вопрос не раскрыт :-) Кто пишет апи по дизайну, бэк или фронт?

[Николай Савельев]

Антон Бреславский, никто тебе вопрос не раскроет. Это интуитивно понятно всем, кто работал в команде.
API по дизайну НЕ ПИШУТ!

Кто пишет апи по дизайну, бэк или фронт?

API пишет бэк. А задача фронта - делать красиво для клиента.

[Антон Бреславский]

Agent Smith, это очень странно звучит.

API по дизайну НЕ ПИШУТ!

Как же тогда понять, что например нужен API /news/summaryчто бы вывести в виджете в боковой панели кол-во новостей в каждой категории? Экономика - 5, Технологии - 10 и т.д. Откуда бэку знать об этом? Менеджер проекта должен сам это понять и поставить такую задачу?

[Николай Савельев]

Антон Бреславский, в хорошей команде такие элементарные вопросы даже не обсуждаются. Всё делается на автомате

[Василий Банников]

Антон Бреславский, Есть продукт, у продукта есть бэклог, в бэклоге идёт разбивка на эпики/фичи/истории.
Вот скорее всего будет фича "виджет новостей" и по нему будет история по аналитике (тут формируется модель данных и API), история по дизайну UI, история по фронту, и история по бэку.

[Антон Бреславский]

Agent Smith, тогда все таки, за наличие API отвечает наличие требования в дизайне?
Значит дизайн это отправная точка для API, а Вы говорите не пишут.

Видим, что виджет есть, нужно особым образом вывести данные, значит и ендпойнт нужен.

в хорошей команде такие элементарные вопросы даже не обсуждаются. Всё делается на автомате

Чистый Agile и все сеньоры? А если дать мидлу и джуну запилить какую-то не сложную фичу.
Пусть спроектирует API, сеньор проверит и заапрувит. Есть такой сценарий?

[Василий Банников]

Антон Бреславский, под дизайном понимается не дизайн пользовательского интерфейса, а system design.
Дизайн UI, Фронт, и бэк могут делаться полностью независимо.

[Антон Бреславский]

Василий Банников, спасибо! Сильный аргумент! Мы забыли про историю пользователя, если конечно ее написали.

[Антон Бреславский]

Василий Банников, тогда, что является отправной точкой для всех них? Фича с описанной историей? По ней дизайнер нарисовал как видит. По ней же бек написал API. По ней же фронт намокал данные. Так?

[Василий Банников]

Антон Бреславский, примерно так, да.
Только не "как видит", а как описано в ТЗ (в плане того, что должно быть изображено)

[Антон Бреславский]

Василий Банников, ну там же не написано какого цвета :-) Получается пока бэк не сделал API и модель данных, фронты не работают? Он же не знают нейминг полей, входные параметры и т.д.?

[Василий Банников]

Антон Бреславский, почему?
Фронты вполне могут верстать, могут какую-то внутреннюю модель данных делать, логику.
А когда появится api - добавить функции для вытаскивания реальных данных.

[Антон Бреславский]

Василий Банников, так они не знают еще нейминг полей и моделей? Откуда им накидывать?

[Василий Банников]

Антон Бреславский, а зачем им знать? Пусть свои придумают, а потом, когда появится API - просто переложат данные в свой вариант.

[Антон Бреславский]

Василий Банников, тогда двойная работа и узкое место :-) Задача по синхронизации работы не решена.

Спасибо за Ваши ответы и участие в дискуссии.

[Vitsliputsli]

Антон Бреславский, двойная работа и узкое место будут тогда, когда вы вместо API нафигачите узкоспециализированные запросы к беку, и при малейших изменениях на фронте или беке придется пределавать много и во многих местах.

[Василий Банников]

Vitsliputsli, +.
Особенно классно будет, если на фронте завязаться на имя поля, которое приходит.
Поменялось апи - переписывай половину кода, кхъ

[Антон Бреславский]

Василий Банников, спасибо, вот тут не понятно. Если в API изменилось имя поля, как Вы оставите на фронте функционал работающим?

[Антон Бреславский]

Vitsliputsli, фронтенд не пишет API, он предлагает. Бекенд смотрит, правит будущий контракт и говорит - погнали, это будет работать так.

[Vitsliputsli]

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

[Антон Бреславский]

Vitsliputsli, это уже слой бизнес логики. На фронте по сути нужны только данные для рендера, как начать разработку интерфейса. Что в бизнес-слое это уже к аналитику.

[Василий Банников]

Антон Бреславский, как как.
Изменилось имя поля - меняю имя поля в слое, где делается запрос к апишке, и происходит перекладываение из/во внутреннюю модель.
Всё

[Антон Бреславский]

Василий Банников, через десериализацию на фронте?

[Василий Банников]

Антон Бреславский, что можно считать за десериализацию?
Если я пишу условно:

function getSomething() {
  const response = await fetch(...);
  const json = await response.json();
  return { internalField: json.apiField, internalField2: json.nested.apiField2 };
}

Это считается за десериализацию?

[Антон Бреславский]

Василий Банников, больше похоже на маппинг.

Мы делаем это так, т.к. можем десериализовать все дерево ответа сразу.

@model()
export class User {

  @field({jsonFieldName: 'first_name'})
  firstName: string;

}

http.get('/users/1').pipe(map(resp => deserialize(resp, User))

У бэка нейминг через snack_case, у нас нормальный cameCase.

[Василий Банников]

Антон Бреславский, да, тоже ок.

Answer 6

[Дамир]

Мне удобна такая схема:
- Смотрю дизайн приложения или прототипы, вникаю как будет работать
- Делаю api, это не так сложно, т.к. понятно какие кнопки что делают, где и как нужно подгружать данные.
- Фронт параллельно делает свою часть и потом подключается к api, обычно в этот момент бывают небольшие правки, добавляются новые параметры запросов.

Comments

[Антон Бреславский]

Спасибо за конструктив. А они паралельно как делают? Вы им дали уже структуру данных и примерные ендпойинты? Как они мокают?

[Дамир]

Антон Бреславский, в первое время эндпоинты не нужны, т.к. делается верстка, если очень надо, можно сделать заглушки запросов со статичным json.

Можно договориться о приоритах, какие экраны нужны в первую очередь.

[Антон Бреславский]

Дамир, с помощью чего вы договаривайтесь о нейминге полей и будущих схемы данных. Фронт и бэк?

[Ярослав Иванов]

Антон Бреславский, что что?)) нейминге?)) почему не просто "название" полей?

[Антон Бреславский]

Ярослав Иванов, наверное профессиональное. Когда-нибудь смотрели https://swagger.io/tools/swaggerhub/ ?

With SwaggerHub, you can accelerate your team’s design process while enforcing quality and style consistency. The API editor makes compliance with Swagger, now referred to as the OpenAPI Specifications (OAS), simple and intuitive.

Accurate, up-to-date documentation is essential to a successful API initiative. With SwaggerHub, you can generate interactive documentation automatically during design, making it easy for both API consumers and internal users to learn and work with your APIs.

Или все таки переброс JSONчиков в чате более оптимально?

Answer 7

[V]

Вам нужно договориться между собой, какое приложение вы делаете:
- SPA или что то подобное
- асинхронное?
- на событиях?
- просто запрос-ответ с данными хтмлем?

Ответив на эти вопросы, будет понятно какое API делать:
- REST
- Graphql
- websocket

Ну и ответив на вопросы выше + посмотрев на макеты экранов можно уже непосредственно накидывать endpointы:
- страница или компоненты будет делать один запрос?
или
- у каждого компоненты свой endpoint API?

Comments

[Антон Бреславский]

Спасибо, но ответ слишком абстрактен. Вы проектировали Swagger в YAML?

[V]

На проектах где был swagger обычно документация генерилась из комментов в коде.

[Антон Бреславский]

V, это стандарное не понимание Swagger - это не "шкурка" в которой можно смотреть чего там на бекенд в API, а это стандарт описания API. Это JSON схема https://github.com/OAI/OpenAPI-Specification/blob/... которая в первую очередь создавалась для API Specification First - сначала опиши как будет, а потом иди программировать.

[V]

Ну это уже на ваш выбор. Обычно код вполне все описывает :)

[Антон Бреславский]

V, тогда зачем что-то документировать? Обсуждать? Согласовывать? Почему сразу не писать код всем сразу? И каждый напишет в итоге, но что-то свое.

[V]

Мы отклонились от сабжа.

Swagger я использовал, только по коментам в коде.

По поводу описывать изначально где то API в json формате, а потом это перегонять в код, ну имхо такое себе, есть другие подходы.

[Антон Бреславский]

V, подход договориться на словах, на бумажке или в чате и сразу в код - получается такой подход, а потом по ходу дела разберемся.

А еще есть другой подход:

Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».

Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.

Ну и как проект для совместного создания API спецификаций https://starkovden.github.io/swaggerhub-introducti...

Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.

Answer 8

[pro100nikTo]

Фронт и бек подчиняются своим руководителям по иерархии выше (субординация) и прямых связей иметь не обязаны. Если по аналогии строительства то каменщик работает по своим чертежам,а моляр по своим. Как и из чего собирает стену каменщик, а какой цвет выберет моляр - это всё детали. Swagger, OpenApi - это тоже детали или способ описания спецификации к АПИ который не обязан существовать (жили как-то и без). Помимо деталей есть и бизнес (ядро, верхний уровень, ...) который не должен зависеть от деталей. Если существует спор то это конфликтная ситуация и если не достигается консенсуса на данном уровне, то дорога к руководству за решением (которое не обязано быть справедливым и верным в понимании последних, оно должно быть однозначным, ясным для всех) иначе результата не будет.