Forward from: Путь аналитика
🤯 POST, PUT или DELETE? - Вот в чем вопрос!
Выбор правильного HTTP-метода для эндпоинта - это вечная холиварная тема. Особенно когда семантика API не маппится напрямую в REST-методы. Например: вроде бы выполняется удаление, но под капотом происходит update или вовсе создание новой записи.
На практике операции редко соответствуют простой схеме «CREATE → POST, UPDATE → PUT, DELETE → DELETE». В реляционных моделях, например, апдейтится сразу много связей.
Не раз на проектах сталкивалась с ситуацией, когда мы с командой буквально застревали в спорах над дизайном API. По бизнес-логике нужно сделать эндпоинты "как бы про удаление" и "как бы про обновление", но по факту операции вызывают комбинацию событий.
Основная сложность таких обсуждений - это найти понятную рамку, на основании чего принимать решение:
🔶 Выбор строго по конвенции REST часто не подходит, так как операция неконвенционная.
🔶 Выбор "по сути" бизнес-операции (например, если удаление, то строго DELETE) ломает REST-конвенцию и упирается в ограничения метода. Может ли DELETE вернуть в response несколько обновлённых сущностей вместо OK/ERROR?
🔶 Выбор в пользу "понятно для клиента" - это размытый критерий. На рынке нет единого стандарта под такие случаи, и «понятность» превращается во вкусовщину.
Как-то обсуждали эту тему с solution architect Володей @vrogach. И его решение мне очень откликнулось.
Конечно, на практике не всегда удаётся договориться о таком с командой. У меня были случаи тоже, когда для сохранения мира в команде приходилось идти за большинством голосом разработчиков и выбирать среди подходов "по сути бизнес операции" пусть и неконвенционно REST.
И всё же я считаю, что подход Владимира наиболее адекватный, особенно для API, где выше требовавания к детерминированности и прозрачности для клиентов. Он максимально понятный и удобный для дальнейшего развития API - не нужно больше возваращаться к выбору метода для новых операций.
💬 А как у вас в командах решают такие спорные случаи? Удаётся ли договориться о едином стандарте? 👇
Выбор правильного HTTP-метода для эндпоинта - это вечная холиварная тема. Особенно когда семантика API не маппится напрямую в REST-методы. Например: вроде бы выполняется удаление, но под капотом происходит update или вовсе создание новой записи.
На практике операции редко соответствуют простой схеме «CREATE → POST, UPDATE → PUT, DELETE → DELETE». В реляционных моделях, например, апдейтится сразу много связей.
Не раз на проектах сталкивалась с ситуацией, когда мы с командой буквально застревали в спорах над дизайном API. По бизнес-логике нужно сделать эндпоинты "как бы про удаление" и "как бы про обновление", но по факту операции вызывают комбинацию событий.
Основная сложность таких обсуждений - это найти понятную рамку, на основании чего принимать решение:
🔶 Выбор строго по конвенции REST часто не подходит, так как операция неконвенционная.
🔶 Выбор "по сути" бизнес-операции (например, если удаление, то строго DELETE) ломает REST-конвенцию и упирается в ограничения метода. Может ли DELETE вернуть в response несколько обновлённых сущностей вместо OK/ERROR?
🔶 Выбор в пользу "понятно для клиента" - это размытый критерий. На рынке нет единого стандарта под такие случаи, и «понятность» превращается во вкусовщину.
Как-то обсуждали эту тему с solution architect Володей @vrogach. И его решение мне очень откликнулось.
Зафиксировать внутренний стандарт для конкретного API (Design Guidelines).
Для всех неконвенционных операций команда один раз договаривается и выбирает конкретный метод, который будет использоваться на все подобные случаи, и фиксирует это в спецификации API.
Например: "Для всех эндпоинтов, которые запускают комбинацию событий, используется POST"
Это делает поведение API предсказуемым для клиентов и разрубает узел нестыковок с REST-конвенцией.
Конечно, на практике не всегда удаётся договориться о таком с командой. У меня были случаи тоже, когда для сохранения мира в команде приходилось идти за большинством голосом разработчиков и выбирать среди подходов "по сути бизнес операции" пусть и неконвенционно REST.
И всё же я считаю, что подход Владимира наиболее адекватный, особенно для API, где выше требовавания к детерминированности и прозрачности для клиентов. Он максимально понятный и удобный для дальнейшего развития API - не нужно больше возваращаться к выбору метода для новых операций.
💬 А как у вас в командах решают такие спорные случаи? Удаётся ли договориться о едином стандарте? 👇