в рамках исследования авторы оценивали влияние применения гайдлайнов и линтеров на качество и скорость разработки API
Результаты показали, что совместное и раздельное использование этих инструментов статзначимо увеличивает производительность создания API и улучшает его с точки зрения пользовательского опыта. Кроме того, они обучили ИИшку на ревью и генерации спецификаций API. И тоже получили хороший результат
я придерживаюсь такого разделения на основании документации по технологиям
Например если заглянуть в официальную доку postgresql, там все аттрибуты в БД указаны через snake_case. И раз авторы технологии так указали, я решила следовать этому стилю при работе с базой
во всех официальных туториалах javascript переменные в основном называются через camelCase, поэтому при работе с JSON (javascript нотация ведь), придерживаюсь такого стиля
ну а где JSON в API, там и остальные параметры, поэтому их в ту же корзинку
не претендую, конечно, на истину, но у меня были такие размышления
The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI.
По определению, данные должны определяться с помощью URI. Посмотрите также первый комментарий от Mnemonik, там подробнее расписано про этот RFC.
Если смотреть философски:
Думаю, что авторы RFC хотели сделать GET методы более легковесными, без Request Body для удобства использования, для облегчения передачи данных, для упрощения кэширования запроса (URL меньше байт займет, чем JSON с теми же параметрами).
Возможно еще для "ошибки от дурака" и более простой поддержки разделения вносить изменения/не вносить изменения: нет Request body - точно идешь по второй ветке, и никакой GET на базу не влияет.
Но это, честно говоря, мои личные домыслы, не судите строго
Если по факту:
Как уже было сказано, в статье и комментариях, Request Body просто отваливается по пути следования GET запроса. И тут против танка не попрешь, как говорится, приходится смириться и принять это за правило.
По моему опыту Request URI покрывает 90% потребностей по передаче параметров. Из основных недостатков - отсутствие типизации и обязательности. Но в остальном, смотрится довольно лаконично. А в более сложных кейсах уже приходится использовать POST.
Либо сначала сохранять POST запросом параметры, получать их айдишку, и по этой айдишке направлять GET запрос - заморочено, но может принести свои бонусы
Если нужно вернуть результат по одному товару и список товаров, конечно нужно делать /products/{productId} и /products?someShit=string соответственно
Но в ресурсе /products и /products/{productId} неправильно возвращать список заявок - ресурс ведь про товар, а не про заявки (в статье ведь рассматривается кейс с заявками)
Можно было бы сделать /products/{productId}/requests - заявки по одному товару и /requests - все заявки
Я как раз об этом пишу. Если бы было сильное различие по бизнесу, стоит разделить, например:
пользователь может видеть заявки по одному товару, но не имеет доступ ко всем заявкам всех пользователей
на экране 1 в заявках по товару мы возвращаем 5 свойств для отображения каждой заявки, а на экране 2 со всеми заявками - по 20 + еще интеграцией что то получаем (тяжеловесная доп. логика)
Но если по бизнес-смыслу (не по требованиям, а именно по смыслу) - это все таки только фильтр - можно и объединить, как я сделала. Так прокатывает конечно не всегда, но можно попробовать в таком поупражняться.
будет два гета: /products/{productId} и /products?someShit=string . я понимаю, что всё исходит из требований к данным, которые нужно поставлять на клиент, макетам и флоу юзера. но, таким образом, мы сможем минимизировать кол-во информации, которую возвращаем в общем запросе, оставив только базовую инфу
если говорить именно про методы на список заявок - по одному товару или по нескольким товарам, то вряд ли. И так и там будет массив с почти одинаковым количеством свойств. Если и там и там будет пагинация (а ее уже только стажеры забывают прикрутить) - то везде будет возвращаться первая десятка например. Одинаковое количество информации получится
Но если система требует суммарно разработку в полтора года, то и по фреймворкам Agile команда суммарно потратит полтора года, а то и больше.
Просто через месяц команда уже выпустит 1/20. Но это будет та самая 1/20 первоочередная фича для пользователя, как я привела в примере декомпозиции.
То есть мы быстрее выпустим первый инкремент, но это не значит что команда будет работать быстрее и быстрее сделает весь «проект».
Так что тут действительно зависит от того, что мы имеем в виду под «быстрой доставкой» - скорость разработки или скорость закрытия первичных потребностей
Спасибо большое за такой развернутый комментарий, некоторые мысли я сохранила себе на подумать!
Но я вообще не рассуждаю "что не так с Agile". Наоборот, я очень привержена ее ценностям и в идеальном мире хотела бы наблюдать, как круто эти ценности реализуются в командах.
Вы пытаетесь вычленить определенную методологию "которую нельзя называть", но на самом деле в основном статья как раз таки про команды, которые не работают по определенному фреймворку/методологии, например Scrum/Kanban или Lean.
Чаще всего в больших компаниях таких чистых методологий не бывает. И в итоге признаки команд, о которых я пишу такие:
а) команды работают итеративно;
б) команды заявляют о гибкости (например могут по потребности запилить новую фичу);
в) организационно это что-то между продуктом и проектом.
Именно с этим связана лексика, которую я использовала ("работают по Agile", "руководитель команды", "менеджер команды", "менеджер продукта" и т.д.), чтобы не относить к определенному фреймворку.
По поводу 10 оттенков менеджера: обычно у таких команд, которые застряли где-то в середине определения своего производственного процесса и методологии, есть некий административный лидер, например тот кто коммитится за бюджет или набирает команду. И он и не совсем Product Owner, и не некий Scrum менеджер, который поддерживает команду, и не Delivery Manager, который отвечает за доставку реализации, а что-то между всем этим и еще разными вариантами. Вот я как раз писала о том, как понять, что этот "менеджер" застрял где-то в середине определения, а с ним и вся команда.
А по поводу жесткой привязки к методологиям, отвечу так: не вижу ничего плохого в том, чтобы набрать инструментов из разных фреймворков. Например взять принцип наполнения релиза, как спринта из Scrum, визуализацию и сервисную модель из Kanban для определенной части команды (для аналитиков например). Важно, чтобы инструмент мог закрыть потребность команды потребности команды в текущем состоянии.
Возьмем например Scrum. Круто, если фреймворк закрывает потребности команды и клиента полностью. Но, при работе с большим бизнес-заказчиком, попробуй ему скажи, что перекраска кнопки пойдет только в следующий спринт, потому что у вас Scrum. Задача ведь - закрыть потребности бизнеса.
Та же ретроспектива несет ценность получения обратной связи и применима как в Scrum, как в Kanban так и в Waterfall в каком то изощренном виде. Основная задача - отслеживание проблем, тюнинг процессов и состояния команды. Ретроспектива - хороший инструмент для этого.
А без нее я даже не знаю как тюнить процесс, разве что ходить на 1-1 встречи с каждым из команды. Поэтому в том числе внесла отсутствие такой механики в список ошибок.
Если бы в реальном мире все было так прозрачно и все работали по прозрачной методологии, которая описана в книжках, было бы очень круто, но так бывает редко, к сожалению
Я с таким встречалась, когда руководителя команды долго убеждаешь, что нужны процессы, планирование, ретро. И он такой - нуууу оооок, давайте.
Начинает это все делать, делает как умеет или не умеет, а потом говорит - да толку нет, давайте так же в телеграме задачи ставить и там же распределять, удобно же!
Я сейчас плотно работаю с командой, в которой и Product Owner и Delivery Manager понимают значимость выстроенных процессов в команде. И как раз грамотная связка (важно, что именно связка) владельца продукта и деливери помогает эти процессы выстроить.
Тогда и продакт лояльно относится к тому что "вот эта маленькая задачка" только в следующую итерацию может попасть, потому что провели регресс только что
И деливери может ожидать от продакта адекватной приоритизации например. Тоже важный элемент без которого далеко не поедешь
да
недавно изучала white paper: "AI-Enhanced API Design: A New Paradigm in Usability and Efficiency" https://dl.acm.org/doi/10.1145/3613905.3650803
в рамках исследования авторы оценивали влияние применения гайдлайнов и линтеров на качество и скорость разработки API
Результаты показали, что совместное и раздельное использование этих инструментов статзначимо увеличивает производительность создания API и улучшает его с точки зрения пользовательского опыта. Кроме того, они обучили ИИшку на ревью и генерации спецификаций API. И тоже получили хороший результат
я придерживаюсь такого разделения на основании документации по технологиям
Например если заглянуть в официальную доку postgresql, там все аттрибуты в БД указаны через snake_case. И раз авторы технологии так указали, я решила следовать этому стилю при работе с базой
во всех официальных туториалах javascript переменные в основном называются через camelCase, поэтому при работе с JSON (javascript нотация ведь), придерживаюсь такого стиля
ну а где JSON в API, там и остальные параметры, поэтому их в ту же корзинку
не претендую, конечно, на истину, но у меня были такие размышления
Если смотреть юридически:
Можно вычитать из RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1:
По определению, данные должны определяться с помощью URI. Посмотрите также первый комментарий от Mnemonik, там подробнее расписано про этот RFC.
Если смотреть философски:
Думаю, что авторы RFC хотели сделать GET методы более легковесными, без Request Body для удобства использования, для облегчения передачи данных, для упрощения кэширования запроса (URL меньше байт займет, чем JSON с теми же параметрами).
Возможно еще для "ошибки от дурака" и более простой поддержки разделения вносить изменения/не вносить изменения: нет Request body - точно идешь по второй ветке, и никакой GET на базу не влияет.
Но это, честно говоря, мои личные домыслы, не судите строго
Если по факту:
Как уже было сказано, в статье и комментариях, Request Body просто отваливается по пути следования GET запроса. И тут против танка не попрешь, как говорится, приходится смириться и принять это за правило.
По моему опыту Request URI покрывает 90% потребностей по передаче параметров. Из основных недостатков - отсутствие типизации и обязательности. Но в остальном, смотрится довольно лаконично. А в более сложных кейсах уже приходится использовать POST.
Либо сначала сохранять POST запросом параметры, получать их айдишку, и по этой айдишке направлять GET запрос - заморочено, но может принести свои бонусы
Круто, сохранила себе такой вариант, спасибо!
Если нужно вернуть результат по одному товару и список товаров, конечно нужно делать
/products/{productId}и/products?someShit=stringсоответственноНо в ресурсе
/products и /products/{productId}неправильно возвращать список заявок - ресурс ведь про товар, а не про заявки (в статье ведь рассматривается кейс с заявками)Можно было бы сделать
/products/{productId}/requests- заявки по одному товару и/requests- все заявкиЯ как раз об этом пишу. Если бы было сильное различие по бизнесу, стоит разделить, например:
пользователь может видеть заявки по одному товару, но не имеет доступ ко всем заявкам всех пользователей
на экране 1 в заявках по товару мы возвращаем 5 свойств для отображения каждой заявки, а на экране 2 со всеми заявками - по 20 + еще интеграцией что то получаем (тяжеловесная доп. логика)
Но если по бизнес-смыслу (не по требованиям, а именно по смыслу) - это все таки только фильтр - можно и объединить, как я сделала. Так прокатывает конечно не всегда, но можно попробовать в таком поупражняться.
если говорить именно про методы на список заявок - по одному товару или по нескольким товарам, то вряд ли. И так и там будет массив с почти одинаковым количеством свойств. Если и там и там будет пагинация (а ее уже только стажеры забывают прикрутить) - то везде будет возвращаться первая десятка например. Одинаковое количество информации получится
спасибо за информацию, я как раз думала о том, как бы правильнее про это написать. теперь буду знать точно)
Вы верно говорите.
Но если система требует суммарно разработку в полтора года, то и по фреймворкам Agile команда суммарно потратит полтора года, а то и больше.
Просто через месяц команда уже выпустит 1/20. Но это будет та самая 1/20 первоочередная фича для пользователя, как я привела в примере декомпозиции.
То есть мы быстрее выпустим первый инкремент, но это не значит что команда будет работать быстрее и быстрее сделает весь «проект».
Так что тут действительно зависит от того, что мы имеем в виду под «быстрой доставкой» - скорость разработки или скорость закрытия первичных потребностей
Как раз писала комментарий, что статья основана на командах, которые занимаются итеративной разработкой :)
в этом как раз основная идеологическая ошибка: думать, что работаешь по Agile, а по факту просто работать итерациями.
Спасибо большое за такой развернутый комментарий, некоторые мысли я сохранила себе на подумать!
Но я вообще не рассуждаю "что не так с Agile". Наоборот, я очень привержена ее ценностям и в идеальном мире хотела бы наблюдать, как круто эти ценности реализуются в командах.
Вы пытаетесь вычленить определенную методологию "которую нельзя называть", но на самом деле в основном статья как раз таки про команды, которые не работают по определенному фреймворку/методологии, например Scrum/Kanban или Lean.
Чаще всего в больших компаниях таких чистых методологий не бывает. И в итоге признаки команд, о которых я пишу такие:
а) команды работают итеративно;
б) команды заявляют о гибкости (например могут по потребности запилить новую фичу);
в) организационно это что-то между продуктом и проектом.
Именно с этим связана лексика, которую я использовала ("работают по Agile", "руководитель команды", "менеджер команды", "менеджер продукта" и т.д.), чтобы не относить к определенному фреймворку.
По поводу 10 оттенков менеджера: обычно у таких команд, которые застряли где-то в середине определения своего производственного процесса и методологии, есть некий административный лидер, например тот кто коммитится за бюджет или набирает команду. И он и не совсем Product Owner, и не некий Scrum менеджер, который поддерживает команду, и не Delivery Manager, который отвечает за доставку реализации, а что-то между всем этим и еще разными вариантами. Вот я как раз писала о том, как понять, что этот "менеджер" застрял где-то в середине определения, а с ним и вся команда.
А по поводу жесткой привязки к методологиям, отвечу так: не вижу ничего плохого в том, чтобы набрать инструментов из разных фреймворков. Например взять принцип наполнения релиза, как спринта из Scrum, визуализацию и сервисную модель из Kanban для определенной части команды (для аналитиков например). Важно, чтобы инструмент мог закрыть потребность команды потребности команды в текущем состоянии.
Возьмем например Scrum. Круто, если фреймворк закрывает потребности команды и клиента полностью. Но, при работе с большим бизнес-заказчиком, попробуй ему скажи, что перекраска кнопки пойдет только в следующий спринт, потому что у вас Scrum. Задача ведь - закрыть потребности бизнеса.
Та же ретроспектива несет ценность получения обратной связи и применима как в Scrum, как в Kanban так и в Waterfall в каком то изощренном виде. Основная задача - отслеживание проблем, тюнинг процессов и состояния команды. Ретроспектива - хороший инструмент для этого.
А без нее я даже не знаю как тюнить процесс, разве что ходить на 1-1 встречи с каждым из команды. Поэтому в том числе внесла отсутствие такой механики в список ошибок.
Если бы в реальном мире все было так прозрачно и все работали по прозрачной методологии, которая описана в книжках, было бы очень круто, но так бывает редко, к сожалению
Я с таким встречалась, когда руководителя команды долго убеждаешь, что нужны процессы, планирование, ретро. И он такой - нуууу оооок, давайте.
Начинает это все делать, делает как умеет или не умеет, а потом говорит - да толку нет, давайте так же в телеграме задачи ставить и там же распределять, удобно же!
Так что если начинать, то начинать надо правильно
Согласна на все 100%
Я сейчас плотно работаю с командой, в которой и Product Owner и Delivery Manager понимают значимость выстроенных процессов в команде. И как раз грамотная связка (важно, что именно связка) владельца продукта и деливери помогает эти процессы выстроить.
Тогда и продакт лояльно относится к тому что "вот эта маленькая задачка" только в следующую итерацию может попасть, потому что провели регресс только что
И деливери может ожидать от продакта адекватной приоритизации например. Тоже важный элемент без которого далеко не поедешь