Данная спецификация является результатом многолетнего использования и рассмотрения различных стандартов WEB API, и является максимально лаконичной адаптацией и “золотой серединой” таковых, учитывая множество факторов:
- Яллонен, ты построил себе новый дом?
- Да.
- И сколько в нем комнат?
- Одна.
- Почему одна?
- Меньше не имеет смысла.
POST /api/v3/some-class/some-action
где
Достаточно только методов POST и GET. Второй при отсутсвии аргументов, но при этом возможно, будет необходимо добавление уникального фейкового аргумента для обновления промежуточных web кэшей.
Использование остальных методов (DELETE, UPDATE, …) рассматривается избыточным и является довольно опасной “смысловой ловушкой”. И занчительно ухудшает миграцию API на иной транспорт, и прочее.
Применение давно используемых, еще с времен началоа Web, параметров в URI возможно, но нежелательно, поскольку также ухудшает маштабирование в сторону более сложно структурированных запросов и RPC. На практике ведет к довольно значительно рефакторингу кода контроллеров бэкэнда.
Параметры
{ "params1": "value", "params2": "value" }
При необходимости, возможна более сложная форма с упаковкой названия метода класса в тело запроса
{ "method": "the-class-method-name", "params": { "param1": "value", "param2": "value" } }
Признаком ошибочности операции служит обязательный признак error
В случае ошибки (исключения, или оного ненормального хода событий) желательно вернуть описание ошибочной ситуации. Само поле message в данном случае являетя обязательным.
{ "error": false, "message": "some description" }
Объект-результат размещается в поле result. Поле message является необязательным.
{ "error": false, "result": { "field1": "value", "field2": "value", "field3": "value" } }
Структура объекта result является предметной, и в принципе ограничена рамками необходимости ( сочетание массивовов структур, структура с массивами и прочее)
Возможно введение допольнительных полей. Например, для потокового асинхронного испольнения нескольких заданий в одном канале возможно введение уникального request-id.
В случае необходимости пакетного исполнения нескольких заданий в одном запросе, спецификация легко маштабируется.
Преобразование Web RPC для работы с бинарно-упакованными форматами также требует относительно малых изменений в коде.