Post #347

Ваше API не REST! Ну и что? Слова "REST API" уже несколько потеряли свой смысл, и только пуристы и зануды вспоминают Леонарда Ричардсона с его четырьмя уровнями зрелости REST API и Роя Филдинга с его диссертацией. Это как Конституция — все слышали, что она есть, но мало кто её сам читал, а уж когда доходит дело до применения... Мы используем http — значит, у нас уже REST! В реальной практике чего только не бывает, и CRUD вокруг ресурса — под что REST наилучшим способом заточен — бывает как раз не так уж часто. В сервисах и микросервисах часто в API выставляют некие функций (у которых даже имена, как у функций: getClientPortfolio, validatePassport, saveFile), и близко не покрывающие матрицу действий по созданию, чтению, изменению и удалению. И это оправдано! Ну вот какой ресурс мы создаем или читаем при проверке паспорта заёмщика? Да мы его просто проверяем. не-REST API — это нормально. Если вы осознанно выбрали этот вариант, и понимаете плюсы и минусы. Удаленный вызов процедуры, RPC, как паттерн имеет смысл. Только давайте будем честны перед собой и не будем называть это REST. С другой стороны, а как называть, если это не SOAP, а что-то более легкое и на JSON-чиках? Вообще, с 2005 года существует и развивается протокол JSON-RPC, сейчас уже версии 2.0. Хотите RPC на JSONах — возьмите хоть что-то более-менее стандартизованное, не изобретайте велосипед. Есть уже готовые реализации протокола почти на любом языке. Официальный сайт https://www.jsonrpc.org/ Есть свой эквивалент сваггера и OpenAPI: OpenRPC, который одновременно и документацию генерит, и работает как WSDL для SOAP — то есть, позволяет получить весь контракт сервиса JSON-RPC. Короче! Не придумывайте свои велосипеды, используйте готовые! В англоязычной среде есть термин 'bikeshadding', "обсуждение сарая для велосипедов". Велосипеды здесь по совпадению, а может быть и нет. Источником является история про комиссию, которая должна была согласовать проект атомной электростанции, но на каждом совещании занималась рассмотрением мелких вопросов вроде сарайчика для велосипедов — из каких он должен быть материалов и где установлен? Другое название этого эффекта — "Закон тривиальности": "Участники обсуждения всегда придают чрезмерное значение тривиальным вопросам" или "Время, потраченное на обсуждение пункта повестки, обратно пропорционально его важности" Это типичное проявление когнитивного искажения, связанного с подменой объекта: мы избегаем думать о сложном и труднодоступном объекте, предпочитая обсуждать нечто другое — явно или неявно. В общем, прекращайте обсуждать сарайчик для велосипедов! Решите главное: у вас REST или RPC. Решили? Берите готовый стандарт: OpenAPI и JSON:API для REST, JSON-RPC или SOAP для RPC, и двигайтесь дальше. Там, глядишь, и до gRPC доживете :)