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

У нас в команде есть вопрос относительно рабочего процесса по разработке 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 с реализованного бэка потом и эта чтука сделает кросс-валидацию и скажет где контракт нарушен - то вообще огонь или нет?

Накидали небольшой скетч идеи. Что скажите? Может быть полезно?
6193819401a11288298281.png
  • Вопрос задан
  • 2387 просмотров
Решения вопроса 1
@slapshin
Мы своей команде используем такой подход: отрисовывается дизайн, фронтендеры анализируют его, решают какие api им нужны для реализации указанного UI, затем кидают задачи на бэк. Бэкенд смотрит предложеный API, если что-то не нравится - общаемся. В принципе, такой подход нас устраивает: фронты пилят UI, бэкэнд реализует бизнес логику, модель данных, занимается оптимизациями производительности и т.д. До этого бэк сам лез в дизайн и продумывал все за фронтов - было не всегда удобно: все таки UI это больше фронтовская тема
Ответ написан
Пригласить эксперта
Ответы на вопрос 7
@Vitsliputsli
Многие фронтендеры относятся к беку, как к некой обертке для работы с базой данной. Когда такие становится лидом команды и начинают диктовать свои требования беку, начинается ад, проект даже с простым беком превращается в нечто монструозное, разваливающиеся на ходу. Но, так как снаружи бек не виден, руководство считает, что дело в отдельных тупых бек-разработчиках, которые артачатся, не хотят работать и увольняются.
Судя по вашим фразам, вы скорее всего один из них. Так как уверены, что приложение - это то, что на фронте, что api - это хрень, которая завязана на отображении информации на фронте, что разработчики бека не нужны при разработке архитектуры и вообще пофиг, что они там делают, главное чтобы давали то, что хочет фронт.
Но, раз вопрос задан, значит сомнения вас посещают. Поэтому: приложение это не только фронт, а зачастую фронт это не самая сложная его часть. Бек - это не обертка над базой данных, и если вы поменяете значение в базе, это не значит, что к примеру, в потоковом вещании сменится кодек (вот, кому-то может и смешно, а мне в такой ситуации ни фига не было весело). С помощью API получают данные, поэтому не важно, что там у вас напроектировали дизайнеры, или как эти данные выводит фронт, API должен быть универсальным и не зависить от того как вы отображаете данные, поэтому, к примеру, бек может вам дать для получения данных несколько универсальных запросов, а не один специальный. В общем, все гораздо сложнее, и ваш вопрос как состыковать фронт и бек перерастает в вопрос как формировать архитектуру проекта, и как управлять командой.
Ответ написан
ddv88
@ddv88
Binance Futures
Судя по описанию у вас команда в целом не понимает что делать и как. А то что делают, делают неправильно.
Стоит начать с того, чтобы найти хорошего лида. Тогда все вопросы о том, кто и что должен делать, и в какой последовательности отпадут сами собой.
Ответ написан
Aetae
@Aetae
Тлен
API разрабатывает бэк, но не по дизайну, а по аналитике от ТЗ.
Если есть только дизайн, то всё равно надо посадить аналитика который по пунктам распишет весь функционал. Иначе будет сказка про лебедя, рака и щуку. Страшная.

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

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

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

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

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

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

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

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

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

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

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

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

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

Лично мне кажется, что это фича ради фичи.
Какие ендпоинты где дёргаются - это фронты и так хорошо знают.
Бэкендеру знать о том, как работает фронт не обязательно.
Дизайнеру также не нужно думать о деталях реализации.
Ответ написан
@ddem
Создаю сайты и web-сервисы
Мне удобна такая схема:
- Смотрю дизайн приложения или прототипы, вникаю как будет работать
- Делаю api, это не так сложно, т.к. понятно какие кнопки что делают, где и как нужно подгружать данные.
- Фронт параллельно делает свою часть и потом подключается к api, обычно в этот момент бывают небольшие правки, добавляются новые параметры запросов.
Ответ написан
kudzu
@kudzu
Вам нужно договориться между собой, какое приложение вы делаете:
- SPA или что то подобное
- асинхронное?
- на событиях?
- просто запрос-ответ с данными хтмлем?

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

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

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы