(Организационный вопрос) Какие есть инструменты и техники разработки API?

Question

[CJRoman]

Добрый день.

Есть 3 команды разработчиков - Бэк-энд, фронт-энд и мобильные разработчики. Бэк-энд пишет API для использования во фронте и мобильщиками. Проблема в том, что фронт и мобильщики не знают, какие end-points созданы, какие изменены, каких входных параметров они ожидают и какого вывода ожидать на выходе.

Какие есть инструменты, или паттерны (кроме человеческого общения, разумеется) для автоматизации, стандартизации и выработки некоего стайлгайда, дабы избежать ежедневных фейспалмов и излишних вопросов "Почему это перестало работать/работает не так как ожадается" и т п.?

Спасибо заранее за ответы.

Comments

[Толстый Лорри]

Автотесты (регрессионные) и настроенный CI. Автоматически запускать с некоторой периодичностью и, если красные, палкой по голому заду девелоперов гонять.

[Alexander Leonchik]

Мы используем GraphQL, вся документация рисуется на ходу, легко менять структуру запросов, возвращаемые значения и аргументы...

Answer 1

[Владимир Куц]

swagger

Comments

[CJRoman]

Используется. Не помогает. Вовремя не ведется, либо все равно мы получаем совсем не то, чего ожидается

[Lander]

CJRoman, Значит низкий фактор ответственности у разработчиков. Нам обычного *.txt хватало для описания API.

[CJRoman]

Lander, А есть способы как с этим бороться? Возможно даже не программными методами, а более организационно? Может есть смысл нарисовать UML-диаграмму с привязкой API-методов по ним?

[Евгений Вольф]

А есть способы как с этим бороться?

Навеяло... Из дневника начальника: сегодня попробовал метод "кнута и пряника", понравилось! Но, пряником бить не удобно, завтра попробую метод "кнута и кнута"...

В нашей работе подобного плана нам хватало:
а) Вики (прямо в репозитории с кодом)
б) Версионирования
в) Заранее определенного плана, что должно делать API (иными словами мы никогда не бросались делать то, что должно делать "непонятно что") :)))

Назначьте ответственного за ведение соотв. документации, swagger'а или текстового файла как озвучил коллега выше.

[Владимир Куц]

> Используется. Не помогает. Вовремя не ведется, либо все равно мы получаем совсем не то, чего ожидается

Ну что тогда сказать... - наверное дело не в инструментах

[Lander]

CJRoman, Не были бы это программисты, можно было бы какой то KPI придумать. С программистами, наверное всё таки лучше аргументировано объяснить что это не тупое исполнилово, а что это на самом деле важно. Донесите мысль что 10 минут, потраченных на актуализацию документации сэкономят часы разборок и выяснений кто виноват.

[Станислав Макаров]

CJRoman какими языками пользуетесь для бэка/фронта?

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

Конечно, тут желательны языки со статической типизацией вроде C#/TypeScript, желательно чтобы для них были библиотеки-генераторы.

[CJRoman]

Станислав Макаров, бэк - Ruby on Rails, фронт - JS/Vue.js

[Станислав Макаров]

CJRoman тогда вариант отпадает) Разве что вы найдёте/сделаете сами генератор простых тестов, который дёргает методы рельсового контроллера и проверяет, что они возвращают адекватный ответ.

[sulla]

CJRoman а можно чуть подробнее вы используете swagger, добавляете новые методы но при этом не пишете ApiDocumentation и не подерживаете в актуальном состоянии?
*так выходит из вашего ответа

тут проблема слегка не техническая: а скорее организационная.
для решения :
1 заставить писать ApiDocumentation и поддерживать в актуальном состоянии. (+0.5 - 1 ч к работе над задачей)
2 заставить писать тесты, покрытие 90и более % для api очень желательно
3 пинать менеджера проекта (этож не Вы?) чтобы вёл актуальную документацию

Сами пишем в похожем стеэке : ROR + Angular/Ember/React - запрос к /api/documentation выгружает json c swagger определением :
{"swagger":"2.0","info":{"version":"1.0","title":"Satyr","description":"Service for.....", "termsOfService" .... }

Фронт/мобил залез глянул что изменилось - поправил.

А вот если Бэк раздолбаи - то тут пара пятничных/понедельничных совещаний с мозгопромывкой, что до сихпорт не отдал Апи фронту помогут_) или Вам придётся искать нового бэка ))

Answer 2

[Сергей Горностаев]

API лучше проектировать и согласовывать до начала разработки.

Answer 3

[Андрей Андреев]

Для API использовал https://github.com/ruby-grape/grape (отлично встраивается в рельсы, можно использовать отдельно)
Гугл подсказывает https://github.com/ruby-grape/grape-swagger для документации(сам не использовал, не было проблемы с документированием)

Плюс минимальные тесты, по которым по желанию можно посмотреть что отдается, а что принимается.

Comments

[CJRoman]

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

[Андрей Андреев]

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

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

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

Answer 4

[Dmitry Pavlov]

Нужно описать API - какие будут endpoints, формат параметров и возвращаемых объектов (request/response).
В этом случае можно накидать API которые на начальной стадии будут возвращать dummy данные (заглушки с hardcoded данными). В этом случае фронтендеры будут иметь что-то для работы и смогут запросить изменения если что-то можно/нужно в API улучшить. Бекенжеры будут работать над своей частью, зная, к какому формату нужно привести данные и какие параметры у них будут на входе.

Поверх API (c фейковыми данными) можно сразу прикрутить какой-то API Explorer / Documentation тул вроде Swagger (для него есть порт на многие стеки разработки). Пример этого petstore.swagger.io

C таким или подобным тулом все всегда смогут зайти и посмотреть какой формат сейчас у API.

Answer 5

[Евгений Воробьев]

:)
Писать все самому без бакэндов и фронтендов

Берешь то что тебе нужно и пишешь