wi12.unix7.org

Данная спецификация является результатом многолетнего использования и рассмотрения различных стандартов WEB API, и является максимально лаконичной адаптацией и “золотой серединой” таковых, учитывая множество факторов:

• жизненного цикла приложений и архитертур,
• различных навыков участников,
• возможностей фреймворков и компиляторов-интерпретаторов,
• стилей кодирования,
• маппинга-маршаллинга-сериализации объектов,
• прочее, прочее.

- Яллонен, ты построил себе новый дом?
- Да.
- И сколько в нем комнат?
- Одна.
- Почему одна?
- Меньше не имеет смысла.

POST /api/v3/some-class/some-action

где

• /api/ - префикс пути для систематизации
• /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 для работы с бинарно-упакованными форматами также требует относительно малых изменений в коде.