Comments 16
Используйте существительные во множественном числе для коллекций. /users.
красиво, но спорное, /user и /user/{id} может быть реализовано шаблонно, соответственно для /users требуется написание дополнительного кода, да и потребителю проще будет дописать к /user идентификатор, я чем использовать разные строки.
Используйте JSON и HTTPS. Это не обсуждается.
тут смешали две разных сущности, https вообще сбоку делается и да, не обсуждается, а json это просто представление данных, при правильном проектирование меняться без проблем практический на любой другой, и да, бывают редкие случаи, когда основным требуется какой-то другой формат.
Еще стоит упомянуть про разницу /user и /user/ если при GET еще можно без проблем сделать редирект, то с POST это уже проблемно.
Рекомендую к прочтению каждому начинающему разработчику
Пагинация - антипаттерн
Сага - костыль который ещё поискать надо
Graphql над rest - ужас,. Почитайте про HARP ( human api rest protocol )
Без конкретики это все больше на вброс похоже. Нужно привести альтернативы, например, если пагинация антипаттерн, то как тогда лучше получать лимитированное количество записей и не убить сервак если в бд десятки миллионов записей?
Я почитал про HARP, (не) спасибо. Другим не советую. Остальным для справки, это от автора самого лучшего фреймворка mol.
Поясните пожалуйста, чем graphql поверх rest (http в данном случае) так плох?
Ничем. Использую именно grafql поверх rest. Вообще никаких проблем нет
Увидели автора а статью не читали
Граф для множества потребителей удобен но имеет свои заморочки, добавляет больше проблем чем решений, делают целые доклады в духе " как мы сделали систему валидации эндпоинтов "
Если у вас уже есть рест готовый, зачем поверх него добавлять граф ? Это же явный оверхэд
А вы про графкл из своего опыта пишете? Исходя из ваших вопросов, кажется, что нет.
Там прямо в стандарте прописано, как работает валидация и как репортятся ошибки. И можно частично загрузить данные при этом (часть графа).
Если у вас есть готовый рест, то графкл очень приятно собирает несколько всех ваших рест ендпоинтов в одну схему. И FE достаточно сделать один запрос, чтобы загрузить связанные данные. Например: фио заказчика, сумму заказа и статус доставки. Которые живут в разных доменах и, возможно, разных сервисах.
Зачастую такие Gateway организуют сами FE разработчики для себя. Чтобы упростить работу со множеством rest endpoint'ов
Да, из своего
Вы описали всё ещё оверхэд, кто то поменяет поля, схема сломается, особенно больно с неподвластным вам вендоров апи
Советую доклады с highload conf на Ютубе по теме
В особенности "graphql зачем он на самом деле нужен"
Мне кажется мы в разных мирах разрабатываем софт
Если кто-то поменяет поля без обратной совместимости, у вас обычные клиенты тоже сломаются. Какая разница, где чинить, в graphql gateway или на клиентах. Тут проблема не в graphql
Доклад может посмотрю. Это он? https://youtu.be/v3m93Xj_BRU?si=5GMaO8k_1Q0YmJeu
По практическим рекомендациям, если ваш API будет использоваться из браузера.
Пункт 2, если у вас API не для раздачи вэбстраниц, используйте POST метод или вэбсокеты или другие методы. К остальным прибегайте когда это требует браузер.
Пункт 3. Если у вас снова не раздача вэбстраниц, то указанный стандарт не для вас.
По пункту 4 все больше кажется что речь не про раздачу вэбстраниц.
Пункт 11. Убедитесь, что кэшируете в нужном месте, хотя ИИ агент легко объяснит пользователю как сбросить кэш, но осадочек останется
Пункт 12. Ага... вы все таки решили поиграть с браузером в игры, подбери нужный http метод, ну вот, теперь выбирайте POST или вэбсокет😉
Пункт 16, это ISO формат, если вы его не узнали.
Пункт 17. Ну это будет прям не просто.... Лучше используйте ту, что возможно. Не надо имитировать курсоры там, где их нет.
Пункт 18. Используйте HTTP как траспорт, не надо искать куда бы ему в красивое место записать, что-то что кажется вам подходящим. Ну явно же не вэбстраницы раздаёте.
Пункт 19. Вы решили, что ваш API не используется в браузере, обмазались HTTP методами, всё красиво, ещё и кэширующие заголовки трогали, но у клиента стоит кэшируюший DPI на выходе. Вот вам и пу-пу-пу.
На последок, любой API с документацией, лучше чем "стандартный REST", который кажется более понятными, но без документации.
REST не REST без гипермедиа. В общем смысле Гипермедиа предназначен для общения с клиентом (браузером) - отдавать контент, управлять кешом, управлять куками и тд. И там формат URL клиента не волнует: вы часто смотрите на URL в браузере, когда лазите по Хабру? или сходу введете в адресной строке url своей статьи? или статьи, которую читали 5 минут назад?. Думаю, нет. Потому что URL в REST выступает идентификатором ресурса для вашего браузера и одновременно ключом кеширования, а не красивым путем для предсказуемости разработчика или пользователя.
В вашем случае описана коммуникация машины с машиной -> RPC over HTTP. Даже если это SPA вызывающие Web API - то URL, которые вызываются из SPA заботят только разработчика, а не пользователя приложения.
Это я к тому, что уже пришла пора перестать заблуждаться и называть API данного типа REST. Достаточно прочитать эту статью от создателя REST, чтобы все встало на свои места.
Да, некоторые концепции из REST используются при разработке Web API, например клиент-сервер и stateless. Но описанные в статье правила это это правила создания RPC сервисов поверх HTTP.
Ресурсориентированный подход хорошо себя показывает только для CRUD. Если мы говорим о чем-то посложнее, начинается появление костылей при использовании этого подхода (пример 1, пример 2, пример 3).
Лично я не вижу в этом смысла. Мне ближе что-то вроде подхода использованного в Slack. Понятная операция, понятные аргументы, не надо ничего выдумывать в дизайне.
При проектировани сразу учитывайте ограничения и возможности клиента. Другими словами, загляните на пару уровней абстракции вниз.
HTTP/2+ поддерживает много параллельных запросов по одному соединению (зависит от настроек сервера, типичные значения 100…128). Может быть, вам не нужен батчинг вообще, а будет только вредить из-за плохого попадания в кэш?
Будет ли апишка дёргаться в браузере с другого домена? CORS — это не просто два заголовка. Это ещё и preflight-запросы, избежав которых можно значительно ускорить общее время запроса. Сюда относятся и кастомные заголовки и организация урлов (эффективное использование access-control-max-age)
Публичность/приватность возвращаемых данных, их время жизни. Если смешать в одном ответе данные с долгим временем жизни и коротким, у всего ответа будет короткое время жизни. Если смешать публичные и приватные (юзер-специфичные) данные, весь ответ станет некэшируемым (чаще всего на практике).
При авторизации через куку и кросс-домене: из-за изоляции запросов или все запросы должны быть с кукой, или все без неё. Иначе браузер может отказаться использовать уже открытое соединение.
… и ещё куча всего, но общий посыл: Абстракции текут, можно сразу подставить ведёрко. Или хотя бы предусмотреть место, куда можно будет в будущем его подставить
Проектирование REST API: проблемы, решения, практические рекомендации