Как вы разрабатываете Rest API?

Question

[Сергей]

Сейчас разработка приложений с использованием Api (SPA и мобильные) выглядит так:

• Пишется ТЗ (больше для клиента, чем для разработчиков)
  
• Бекендер составляет фикстуры end-поинтов (json файлы или объекты в js)
  
• Если нужна работы с внешним сервером, бекендер пишет ТЗ для того, что требуется от них
  
• Бекендер пишет код и создает в Postman по нему проект и изменяет абстрактные фикстуры на более реальные по мере написания end-поинтов
  
• Фронтендер пишет приложение по фикстурам и документации из Postman по мере их создания
  
• Всё дружно тестируется ручками
  

Сейчас хочется для начала уйти как минимум от фикстур и перейти на mock сервер, который автоматически бы генерировался по OpenAPI (swagger) схемам с фейковыми данными. Но пока не смог поднять нормально mock сервер prism.

Гугл ищет в основном основы вроде https://habr.com/post/351890/

Можете поделиться своими методами работы?

Answer 1

[float64]

Поддерживаю тему с graphql - но тут надо понимать что для того чтобы его применять вам все равно нужно сначала создать REST API с основными CRUD-операциями из которых graphql уже будет собирать все что нужно.

По основной теме могу сказать что лучший подход для создания REST API с автоматической генерации Swagger/Open API спецификации который я видел называется "Model Driven Design" - вот статья о нем: https://strongloop.com/strongblog/node-js-api-tip-...

Статья от разработчиков loopback framework: https://loopback.io

Судя по вашему вопросу у вас бекенд на js поэтому можете попробовать его - это как раз специализированный фреймворк для создания API-серверов. Генерирует весь APi для всех моделей приложения автоматически + методы для всех реляционных связей + позволяет добавлять свои методы.

Для PHP-стека тоже есть решение: https://api-platform.com но оно пока что уступает loopback из-за неполной поддержки автоматического создания эндпоинтов для реляционных связей.

Моя рекомендация:
1) Прочитать про model driven design
2) Составить список моделей вашего приложения
3) Прописать поля, методы и связи каждой модели
4) Сгенерировать API по полученному описанию, документировать, приправить лучком, подать на стол

Answer 2

[Алексей]

Может вам посмотреть в сторону GraphQL https://graphql.org/ сервера или как прослойку между сервером и клиентом?)

Думаю уже все наслышаны что это, но я повторюсь какие плюсы дает GraphQL:
* самодокументируемое api
* понимание, что вы должны отправить и что получите
* получаете только то что просите
* типизация данных (как входных, так и выходных)
* понятная документация
Скорее всего я что то забыл, но можно почитать получше и понять что и как

Минусы тоже конечно есть, но плюсы перебивают их)

А если говорить про поводу прослойки, например на nodejs, то появляется еще куча дополнительных возможностей помимо GraphQL, то есть используя тот же apollo для express можно сделать очень хорошие качественные моки для вашего клиента, могу рассказать подробнее если интересно)

Если есть вопросы, спрашивайте, постараюсь ответить на них)

Comments

[Сергей]

Спасибо за ответ. С GraphQL не сталкивался еще, только на хабре заголовки читал)
Можете подсказать ссылку на пример проекта, что-бы посмотреть как оно в реальности работает?

[Олег Гамега]

Сергей, апи гитхаба на нем, фэйсбука (что как бы естесвенно) ну и куча других
https://www.youtube.com/watch?v=jrJQ2B027Xk&
https://www.youtube.com/watch?v=F4vHSHzpO1g&t=2425s

Answer 3

[Олег Гамега]

Пишется ТЗ (больше для клиента, чем для разработчиков)

ТЗ в первую очередь нужно разработчиков

Фронтендер пишет приложение по фикстурам и документации из Postman по мере их создания

документацию по апи должен писать фронтенд разработчик ориентируясь на дизайн - ему же с этим работать

зы планируем уходить на graphql

Comments

[Алексей]

Не совсем согласен с вашим утверждением, что доку по api должен писать фронтэнд разработчик, мое мнение такое, это зависит от того, какое у вас api: публичное или нет, то есть использовать его будет только ваше веб приложение или пользователем api может быть и обычный пользователь...в первом случае возможно пусть фронт как то рулит апи, там уж ваше дело, но вот во втором случае должен делать тот кто делает эту api)

[Олег Гамега]

mrAlexRabota, как правило нет проблемы реализовать апи, проблема сделать его удобным

[Алексей]

Олег Гамега, не ну тут я с вами согласен, тут наши мнения совпадают)

[Сергей]

Мне кажется что документацию все-же должен писать бекенд. Именно он (в нашей команде) разрабатывает апи и продумывает структуру приложения (энд-поинты, сущности). Фронтендер лишь берет данные, которые ему предоставили. Бекенд по прототипу+тз+верстке уже знает какие данные необходимы будут фронту.

ТЗ в первую очередь нужно разработчиков

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

[Олег Гамега]

Сергей, фиговое тз не нужно ни кому (фиговое тз даже клиенту слать не стоит, проблем от него больше)
если тз на апи пишется на основе дизайна то тогда нормально, хотя как всегда есть ньюансы

Переучить не получается(

пороть пробовали ?)

Answer 4

[Алексей Николаев]

Можете поделиться своими методами работы?

Как-то у вас все сложно. У меня просто: пишется API, потом все это вносится в Postman, тестируется то, что не было с матюками протестировано в процессе работы и сдается.

Comments

[Сергей]

А как фронт работает до того, как вы написали API и внесли его в Postman?

[Алексей Николаев]

Сергей, зачастую я же фронт и разрабатываю. Впрочем, если фронт разрабатываю не я, то новые эндпойнты подаются фронту по мере разработки. Иногда переименовываются в процессе.

Answer 5

[oldhowl]

Postman не юзаем как таковой. Для документации API используем swagger в связке с .net core, на нём же кодогенерируем API клиента для фронта. Проблем никогда не возникало и время экономит много.
Пока пилим бек, фронт верстает страницы, отдаем бек частями. Просто согласовываем что пилим и параллельно работаем.

Answer 6

[chibitko]

.net (core) + swashbuckle
фронтеры пишут прототип, постепенно прикручивая api