в рамках исследования авторы оценивали влияние применения гайдлайнов и линтеров на качество и скорость разработки 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 понимают значимость выстроенных процессов в команде. И как раз грамотная связка (важно, что именно связка) владельца продукта и деливери помогает эти процессы выстроить.
Тогда и продакт лояльно относится к тому что "вот эта маленькая задачка" только в следующую итерацию может попасть, потому что провели регресс только что
И деливери может ожидать от продакта адекватной приоритизации например. Тоже важный элемент без которого далеко не поедешь
Information
Rating
Does not participate
Registered
Activity
Specialization
Системный аналитик, Архитектор программного обеспечения
да
недавно изучала 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 понимают значимость выстроенных процессов в команде. И как раз грамотная связка (важно, что именно связка) владельца продукта и деливери помогает эти процессы выстроить.
Тогда и продакт лояльно относится к тому что "вот эта маленькая задачка" только в следующую итерацию может попасть, потому что провели регресс только что
И деливери может ожидать от продакта адекватной приоритизации например. Тоже важный элемент без которого далеко не поедешь