RESTful: зачем?

Вопрос не столько по .NET Core (хотя реализации на нём), сколько общего характера.

Какой практический смысл строго соблюдать базовые принипы RESTful? Вот те самые, что URL - это ресурс (в т.ч. многоуровневый), а HTTP-методы - действия над ресурсами. И ещё, что все методы одного ресурса оперируют исключительно однотипными объектами, т.е. если GET/id возвращает 'SomeDto', то PUT и POST должны принимать на вход его и только его.

И почему некоторые фронтэндеры (да и бэкэндеры из других языков) так рьяно пытаются это продвигать? Вживую пытался спрашивать, но так суть и не уловил.

Там что ли на стороне фронтэнд-фреймворков возникают какие-то непроходимые сложности при работе за пределами этой идеологии?

Просто с точки зрения десктоп-бэкэндера как ни пытаюсь, не могу впихнуть логику даже мало-мальски сложного бизнес-объекта в эти рамки. Т.е. если это простой справочник, то да, всё красиво, но как только появляется какая-нибудь сложная сущность типа "счёт", то она сразу же обрастает толпой кастомных специфичных действий, которые либо вообще сущность не меняют и не возвращают, либо затрагивают отдельные её части, либо требуют на вход/выход специфичные DTO, которые в хранилище не мапятся.

Но при этом с точки зрения REST нельзя использовать [POST] /api/1.4/invoices/42/recalcStatus/, ибо это уже не REST, т.к. глагол в урле.

Да и даже на примере справочника возникают казусы:
[GET] /api/1.6/towns/42 => 'TownDto'.
[GET] /api/1.6/towns => 'IEnumerable<TownDto>'.

И если вдруг сущность слишком жирная и в некоторых сценариях требуется вернуть коллекцию 'TownShortDto', то вот так уже нельзя:
[GET] /api/1.6/towns => 'IEnumerable<TownShortDto>'.
Т.к. данный URL уже занят.
Говорят, можно использовать такой вот преподвыверт:
[GET] /api/1.6/shortTowns => 'IEnumerable<TownShortDto>'.
Но выглядит это запутанно - ведь с точки зрения БЛ это, по сути, один тот же объект предметной области, просто немного в разной комплектации. Да и это вырожденный ресурс получается, т.к., скорее всего, на нём не получится реализовать методы добавления/обновления, т.к. 'TownShortDto' попросту не содержит всех нужных данных.

И так тоже нельзя:
[GET] /api/1.6/towns/?shotMode=true => 'IEnumerable<TownShortDto>'.
Т.к. параметры запроса к URL не относятся.

И так тоже не канон:
[GET] /api/1.6/towns/shortMode => 'IEnumerable<TownShortDto>'.[/INLINE]
Т.к. URL - это ресурс, а 'shortMode' под это понятие не особо подпадает с точки зрения REST.

P.S.: в общем, если кому несложно, поделитесь личным опытом, зачем, почему и актуально ли вообще следовать этому на проектах со сложной бизнес-логикой?

0

Сообщение от kotelok Но при этом с точки зрения REST нельзя использовать [POST] /api/1.4/invoices/42/recalcStatus/, ибо это уже не REST, т.к. глагол в урле.

Работал на двух больших проектах с REST архитектурой API. В обоих использовались подобные кастомные действия.
Вопрос очень популярный в интернетах. Чтобы не нарушать каноны предлагаются достаточно дикие решения CRUD действиями доводить обьект до нужного состояния, например в данном случае установить поле Invoice.Status = RecalcStatusRequested, а сервис должен триггерить нужные действия при таком апдэйте.

Сообщение от kotelok [GET] /api/1.6/towns/?shotMode=true => 'IEnumerable<TownShortDto>'.

Мне норм выглядит. Канонический url ресурса с дополнительным параметром запроса.

Сообщение от kotelok Какой практический смысл строго соблюдать базовые принипы RESTful?

Какой практический смысл стандартов? Чтобы все было единообразно.
Не вижу ничего плохого в расширении RESTful правилами нужными для проекта, главное знать меру, чтоб API не превратились в зоопарк.

В случае столкновения с подобного рода RESTful эвангелистами советую в качестве аргументов предоставлять API больших и известных сервисов, например Google Cloud Platform.

1

Сообщение от nicolas2008 Мне норм выглядит

Выглядит-то норм, но только вот стандартные .NET-библиотеки такого не понимают, т.е. такой вот код хоть и компилируем с точки зрения C#:Но в рантайме:
1. Роутер не может разрешить маршрут, т.к. на одном и том же урле два метода с разной сигнатурой и возвращаемыми параметрами.
2. Сваггер падает по той же причине.

Т.е. либо оставаться в рамках REST через вырожденные ресурсы типа /api/shortTowns, и не забывать "связывать" их с базовым ресурсом чисто на уровне документации (чтобы потребитель API осознваал, что ID в обоих ресурсах это одно и то же с точки зрения БЛ, чтобы потребитель не озадачивался, почему это в 'shortTowns' нет добавления/обновления).

Либо отходить от канона и делать [GET] /api/towns/onlyNames, а в документации оговаривать, что все ресурсы исключительно одноуровневые, что первый уровень - всегда ресурс, второй и далее уровень - ID сущностей, вариации возвращемых значений и кастомные действия (в зависимости от контекста или HTTP-метода), прочие параметры - стандартно через параметры запроса после вопросика.

0

я так не заморачивался, мне казалось гораздо важней чтоб юзеру(фронту) было удобно, при этом своя кухня работала быстро и эффективно
если нужен Short делал просто Short и всё, как удобно в конкретном случае(чаще /api/1.6/towns). Правило YAGNI никто не отменял кстати, бесполезных методов апи должно быть как можно меньше
фронтовикам строго до лампочки эти рестфулы - главное чтоб данные адекватные и понятные были.
никто же не дергает апи просто ради веселья вечером - нужно отобразить в гриде дергают данные, данных хватило - отлично, все счастливы. а рестфул там или нет..

1

Сообщение от nicolas2008 например в данном случае установить поле Invoice.Status = RecalcStatusRequested

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

Но может быть и что-нибудь куда более комплексное, например, действие [POST]/api/invoices/42/sendToExternalStorage. Которое проверит условия, выполнит отправку согласно параметрам счёта, обновит статусные поля, вернёт "ок" (или сущность целиком, или специфичный DTO). И вот в таком виде оно вполне логично и понятно выглядит - сущность "счёт", ID=42, действие - отправить. И вот это уже внутрь CRUD заворачивать совсем трэшово получается.

Можно, конечно, снова использовать преподвыверт с фэйковым ресурсом: [POST]/api/externalInvoices (и в теле передавать ID счёта). Но это ведь ещё менее очевидное решение получается, т.к. выглядит оно как простой POST-запрос, т.е. запрос на создание ресурса 'externalInvoice', а по факту:
0. Валидирует сущность из коллекции 'invoices'.
1. Выполняет отправку другого ресурса (invoices) на внешний сервис.
2. Модифицирует другой (invoices) ресурс.
3. Возвращет ID, который нам не особо нужен.
4. А клиент потом ещё вынужден делать дополнительный запрос к ресурсу 'invoices', чтобы получить актуальное состояние сущности. Ну или в п.3, внезапно, в ответ прилетает экземпляр из коллекции 'invoices'.

0

Сообщение от kotelok Но может быть и что-нибудь куда более комплексное, например, действие [POST]/api/invoices/42/sendToExternalStorage. Которое проверит условия, выполнит отправку согласно параметрам счёта, обновит статусные поля, вернёт "ок" (или сущность целиком, или специфичный DTO). И вот в таком виде оно вполне логично и понятно выглядит - сущность "счёт", ID=42, действие - отправить. И вот это уже внутрь CRUD заворачивать совсем трэшово получается.

Для целей апдейта сущностей есть методы PUT и PATCH
POST используется для создания сущности.

т.е. [POST]/api/invoices - создаем сущность. модель для создания должна лежать в теле.

[PUT]/api/invoices/42 - обновляем сущность с id=42. Модель для обновления в теле

[PATCH]/api/invoices/42 - а это для мелочевки, если надо обновить не всю сущность, а некоторые свойства. Список свойств с данными можно положить в тело, а можно и в параметры запроса.

Сообщение от kotelok И почему некоторые фронтэндеры (да и бэкэндеры из других языков) так рьяно пытаются это продвигать? Вживую пытался спрашивать, но так суть и не уловил.

потому что достаточная удобная штука для работы со структуированными данными. Тут главное правильно развернуть роуты, тогда станет намного понятнее. Пример:

GET api/{entity}/{id} - получаем модель сущности
POST api/{entity} - создаем сущность
PUT api/{entity}/{id} - обновляем сущность
DELETE api/{entity}/{id} - соотв удаляем

Если в модели сущности имеются списочные данные, а они в 90% случаем есть, то тогда роуты выстраиваем по принципу от главной к зависимой:

GET api/{entity}/{id}/{subentity}/{subid} - получаем модель сущности
POST api/{entity}/{id}/{subentity} - создаем сущность
PUT api/{entity}/{id}/{subentity}/{subid} - обновляем сущность
DELETE api/{entity}/{id}/{subentity}/{subid} - соотв удаляем

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

Главный принцип - не держать состояние модели. В этом отличие REST от RESTfull. Еще во времена SOAP при работе с сущностью удерживалась сессия и можно было не передавать в разных запросах ид, логины и т.д. С SOAP 10 лет назад много кто работал, даже сейчас сервисы писаные 10 лет назад на нем работают и не сказал бы что это удобно. Пример: turbosms - украинский смс провайдер. Но SOAP канул и сгинул и программисты придумали REST. Сейчас пользуются им. Что будет через 10 лет - еще что-нить придумают.

Сообщение от nicolas2008 В случае столкновения с подобного рода RESTful эвангелистами советую в качестве аргументов предоставлять API больших и известных сервисов, например Google Cloud Platform.

Берем гугловское апи в разделе Calendar API, которое работает по RESTfull
Тынц....

Добавлено через 10 минут

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

Я думаю, что эту фигню начали повсеместно внедрять, потому что апи большой и над ним может работать несколько команд и тогда ставится вопрос однотипности. В тот же сваггер REST проще скидывать, если он подчинен общим правилам. Ну это ятд

1

kotelok, shortMode это параметр одного метода, не надо создавать два.

Берем гугловское апи в разделе Calendar API, которое работает по RESTfull

yurickas, и? какок вывод?

0

yurickas
Ну так а обозначеныне главные две проблемы как решать-то )?

1. Когда для сущности требуется вернуть с сервера не сущность целиком, а только пару полей в виде соответствующего 'SimpleDto'. И, возможно, ещё какуой-нибудь DTO под конкретный кусочек фронтэнда, чтобы не тянуть пол-базы каждый раз. И, желательно, не создавая для этого фэйк-сущность.

2. Когда сущность не надо обновлять/добавлять/удалять, но для неё нужно выполнить какой-то custom-action, специфичный для предметной области.

Добавлено через 7 минут
Например, вполне типичная задача, когда есть некий справочник:И для него надо на форме показать комбобокс на базе свойства 'Name' (не вытягивая на клиент не нужный пока 'HugeDescription'). А если пользователь кликнул в запись, то по 'ItemId' сделать запрос уже полной версии и показать пользователю 'HugeDescritpion'. При этом, метод запроса всего справочника со всеми полями так же может быть востребован в каких-то сценариях, т.е. он тоже должен остаться в API.

Добавлено через 16 минут

Сообщение от nicolas2008 shortMode это параметр одного метода, не надо создавать два.

Тогда этот метод не сможет вернуть типизированный DTO, т.к. в одном случае там будет 'SomeDto', в другом 'SomeSimpleDto', в третьем 'SomeOtherDto', с разным составом полей. И методу придётся возвращать 'object', и в сваггере тогда будет беда с документацией.

0

Сообщение от kotelok И для него надо на форме показать комбобокс на базе свойства 'Name' (не вытягивая на клиент не нужный пока 'HugeDescription'). А если пользователь кликнул в запись, то по 'ItemId' сделать запрос уже полной версии и показать пользователю 'HugeDescritpion'. При этом, метод запроса всего справочника со всеми полями так же может быть востребован в каких-то сценариях, т.е. он тоже должен остаться в API.

Ну, есть паттерн mvvm. На стороне сервера работаем с сущностями, отдаем их вьюмодели, принимаем вьюмодели и по ним работаем с сущностями. Перевод из одного в другое проводится или ручками, или сторонними библиотеками типа Automapper. Отдавать можно и json, а можно и xml. Кому как угодно

Сообщение от nicolas2008 yurickas, и? какок вывод?

Ну, контекст вопроса был в том, что для того чтобы заткнуть рот "евангелистам"© от REST - надо ткнуть их носом в гугловский апи, который не REST. Я ткнул в обратное....

Добавлено через 5 минут

Сообщение от kotelok Тогда этот метод не сможет вернуть типизированный DTO, т.к. в одном случае там будет 'SomeDto', в другом 'SomeSimpleDto', в третьем 'SomeOtherDto', с разным составом полей. И методу придётся возвращать 'object', и в сваггере тогда будет беда с документацией.

ну так и говорю. Вьюмодели. В вьюмодель можешь засунуть что угодно.

Если сервер отдает json строго по модели БД, то первый краш апи который можно получить - это парсинг циклических ссылок из object в json.

1

Сообщение от kotelok А если пользователь кликнул в запись, то по 'ItemId' сделать запрос уже полной версии и показать пользователю 'HugeDescritpion'.

А если пользователь захотел 10 раз кликнуть по кнопке для получения полной версии сущности, то все, запинать сервер до смерти?
Как-то делали сервис для централизованного управления рекламой (BING, Google AdWords), у бинга вроде было две версии API в том числе bulk loading, то есть когда грузим очень много толстых(!) объектов, зато потом не пинаем сервер вообще. С тех пор и взял за основу загружать весь граф объекта, что-то скрывать первоначально, если нужно, а обновлять по кускам.

Сообщение от kotelok Например, вполне типичная задача, когда есть некий справочник:

Ну и тут я бы сделал также.

1

Сообщение от yurickas Ну, контекст вопроса был в том, что для того чтобы заткнуть рот "евангелистам"© от REST - надо ткнуть их носом в гугловский апи, который не REST. Я ткнул в обратное....

Хотите сказать что у гугла все API соответствуют правилам REST?
Гляньте это
https://cloud.google.com/kuber... ence/rest/

0

Сообщение от nicolas2008 Хотите сказать что у гугла все API соответствуют правилам REST?

Нет. Не хочу. И даже никогда этого не утверждал, а вот некоторые звездоболы утверждают. Тот же апи по календарям есть и в формате SOAP. Реализован для совместимости с CalDav.

Добавлено через 2 минуты

Сообщение от nicolas2008 Гляньте это

Глянул. Особенно понравился вот этот абзац, сорри за гугл-переводчик, но я думаю у Вам с английским лучше сами прочитали в первоисточнике.

Discovery Document - это машиночитаемая спецификация для описания и использования REST API. Он используется для создания клиентских библиотек, плагинов IDE и других инструментов, которые взаимодействуют с API Google. Одна служба может предоставлять несколько документов обнаружения. Эта служба предоставляет следующие документы обнаружения:

0

Сообщение от yurickas Нет. Не хочу. И даже никогда этого не утверждал, а вот некоторые звездоболы утверждают.

К чему тогда комментарий о Calendar API?

0