User Tools

Site Tools


Simple WEB API

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

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

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

Request

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

где

  • /api/ - префикс пути для систематизации
  • /some-class/ - обозначение класса объектов, или модуля, или функциональной группы.
  • /some-action/ - обозначание метода

Достаточно только методов POST и GET. Второй при отсутсвии аргументов, но при этом возможно, будет необходимо добавление уникального фейкового аргумента для обновления промежуточных web кэшей.

Использование остальных методов (DELETE, UPDATE, …) рассматривается избыточным и является довольно опасной “смысловой ловушкой”. И занчительно ухудшает миграцию API на иной транспорт, и прочее.

Применение давно используемых, еще с времен началоа Web, параметров в URI возможно, но нежелательно, поскольку также ухудшает маштабирование в сторону более сложно структурированных запросов и RPC. На практике ведет к довольно значительно рефакторингу кода контроллеров бэкэнда.

Body

Параметры

{ 
    "params1": "value", 
    "params2": "value" 
}

При необходимости, возможна более сложная форма с упаковкой названия метода класса в тело запроса

{ 
   "method": "the-class-method-name",
   "params": {
       "param1": "value", 
       "param2": "value"
    } 
}

Response

Признаком ошибочности операции служит обязательный признак error

Operation has Error

В случае ошибки (исключения, или оного ненормального хода событий) желательно вернуть описание ошибочной ситуации. Само поле message в данном случае являетя обязательным.

{ 
  "error": false, 
  "message": "some description" 
}

Operation is Fine

Объект-результат размещается в поле result. Поле message является необязательным.

{ 
    "error": false, 
    "result": {
        "field1": "value",
        "field2": "value",
        "field3": "value"
    }
}

Структура объекта result является предметной, и в принципе ограничена рамками необходимости ( сочетание массивовов структур, структура с массивами и прочее)

Развитие

Возможно введение допольнительных полей. Например, для потокового асинхронного испольнения нескольких заданий в одном канале возможно введение уникального request-id.

В случае необходимости пакетного исполнения нескольких заданий в одном запросе, спецификация легко маштабируется.

Преобразование Web RPC для работы с бинарно-упакованными форматами также требует относительно малых изменений в коде.