Спецификация OpenRPC

Предисловие

Перевожу данную спецификацию с расчетом, что смогу реализовать JSON-RPC с документированием через HTTP сервисы 1С. Сделать что-то вразумительное в стиле REST не получилось, сказалось отсутствие инструментария на уровне платформы (RegExp до сих пор не завезли). Вижу в качестве решения что перед 1С будет стоять прокси, в котором удобно реализовать современные протоколы, а 1С использовать как back-back-end. JSON-RPC стилистически похож на SOAP, но более легковесный (наличие автодокументации с JSON схемами перекрывает использование wsdl схем). Вопрос с валидацией схем пока открыт, есть наработки //infostart.ru/public/1265429/, но обвязки хранения и использования в контексте сервера еще не реализовано.

"|" - обозначает ИЛИ

"[]" - обозначает массив элементов

"GitHub Flavored Markdown", часто сокращаемый как GFM, - это диалект Markdown, который в настоящее время поддерживается для пользовательского контента на GitHub.com и GitHub Enterprise.

Введение

Спецификация OpenRPC определяет стандартное, не зависящее от языка программирования описание интерфейса для API JSON-RPC 2.0, которое позволяет как людям, так и компьютерам обнаруживать и понимать возможности службы, не требуя доступа к исходному коду, дополнительной документации или проверки сетевого трафика. При правильном определении через OpenRPC потребитель может понимать и взаимодействовать с удаленной службой с минимальным количеством логики реализации. Подобно описаниям интерфейсов для программирования более низкого уровня, спецификация OpenRPC устраняет догадки при вызове службы.

Варианты использования для машиночитаемых документов определения API JSON-RPC включают, но не ограничиваются:

• интерактивная документация
• генерация кода по документации
• клиенты
• серверы
• автоматизация тестирования.

Документы OpenRPC описывают API-сервисы JSON-RPC и представлены в формате JSON. Эти документы могут создаваться и обслуживаться статически или динамически из приложения.

Спецификация OpenRPC не требует переписывания существующих API JSON-RPC. Он не требует привязки какого-либо программного обеспечения к сервису - описываемый сервис может даже не принадлежать создателю его описания. Однако требуется, чтобы возможности службы были описаны в структуре спецификации OpenRPC. Не все сервисы могут быть описаны OpenRPC — эта спецификация не предназначена для покрытия API REST - она предназначена исключительно для API, которые придерживаются спецификации JSON-RPC 2.0. Спецификация OpenRPC не требует определенного процесса разработки, такого как design-first или code-first. Это облегчает любой метод, устанавливая четкие взаимодействия с API JSON-RPC.

Определения

Документ OpenRPC
Документ (или набор документов), который определяет или описывает API. Документ OpenRPC использует спецификацию OpenRPC и соответствует ей.

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

Регулярное выражение
В спецификации OpenRPC и инструментах рекомендуется использовать регулярные выражения, совместимые с Perl. При этом разработчики инструментов ДОЛЖНЫ придерживаться регулярных выражений ECMA-262 6th Edition.

Официальный OpenRPC инструментарий (Tooling)

Инструмент, который создается, поддерживается и документируется организацией OpenRPC. Он предназначен для использования в качестве функциональной эталонной реализации спецификации. Пользователям спецификации OpenRPC рекомендуется создавать версии инструмента как свою собственные организации/проекты.

Примечание переводчика: Ссылки на инструменты https://open-rpc.org/developers

• https://playground.open-rpc.org/
• https://marketplace.visualstudio.com/items?itemName=OPEN-RPC.OPEN-RPC

Версии

Спецификация OpenRPC версионируется с использованием семантического управления версиями 2.0.0.

Часть версии"major.minor" (например, 1.0.x) ДОЛЖНА обозначать набор функций OpenRPC. Как правило, версии ".patch" устраняют ошибки в этом документе, а не в наборе функций. Инструментарий, поддерживающий OpenRPC 1.0.0, ДОЛЖЕН быть совместим со всеми версиями OpenRPC 1.0.x. Версия исправления НЕ ДОЛЖНА учитываться инструментами, не делая различий, например, между 1.0.0 и 1.0.1.

Последующие выпуски второстепенных версий спецификации OpenRPC (увеличение "minor" номера версии) НЕ должно мешать инструменту, разработанному для более низкой младшей версии и той же основной версии. Таким образом, гипотетическая 1.1.0 спецификация ДОЛЖНА использоваться с инструментами, предназначенными для 1.0.0.

Документ OpenRPC, совместимый с OpenRPC 1.0.0, содержит обязательное "openrpc" поле, которое обозначает семантическую версию OpenRPC, которую он использует.

Формат

Документ OpenRPC, соответствующий спецификации OpenRPC, сам по себе является объектом JSON, который должен быть представлен в формате JSON. Из-за характера API-интерфейсов JSON-RPC, использующих форматы JSON, строго используйте JSON только так, как описано здесь. Если вы хотите использовать любой другой формат, кроме JSON, он должен быть преобразован вне любого инструмента OpenRPC.

Примечание переводчика: для ручного формирования документации удобнее использовать YAML, проверено на Swagger/OpenAPI, но позиция авторов такова что "только JSON", https://github.com/open-rpc/spec/issues/265. Использовать конвертер JSON<->YAML ради удобного просмотра или формирования без автодополнения неудобно.

Рекомендуется, чтобы документ OpenRPC назывался: openrpc.json. Инструмент , для ввода которого требуется документ OpenRPC, МОЖЕТ принять расположение документа по умолчанию "./openrpc.json", где "./" представляет текущий рабочий каталог.

Все имена полей в спецификации чувствительны к регистру. camelCase СЛЕДУЕТ использовать для всех ключевых имен. Сюда входят все поля, которые используются в качестве ключей в соответствии (map), за исключением случаев, когда явно указано, что ключи нечувствительны к регистру.

Согласно спецификации JSON для объектов, имена ключей ДОЛЖНЫ быть уникальными. Однако, чтобы избежать двусмысленности, все шаблонные поля в документе OpenRPC ДОЛЖНЫ иметь уникальные имена ключей внутри содержащего объекта.

Форматирование текста

Все поля спецификации "description" отмечены как поддерживающие форматирование Github markdown. Там, где инструмент OpenRPC отображает форматированный текст, он ДОЛЖЕН поддерживать, как минимум, синтаксис markdown, как описано в GitHub Flavored Markdown. Tooling МОЖЕТ игнорировать некоторые функции "GitHub Flavored Markdown" для решения проблем безопасности.

Метод обнаружения службы

API JSON-RPC могут поддерживать спецификацию OpenRPC, реализуя метод обнаружения служб, который возвращает схему OpenRPC для API JSON-RPC. Метод ДОЛЖЕН быть назван "rpc.discover." "rpc." префикс является зарезервированным префиксом метода для системных расширений спецификации JSON-RPC 2.0. Ниже приведена спецификация OpenRPC для метода обнаружения службы:

{
  "methods": [
    {
      "name": "rpc.discover",
      "description": "Returns an OpenRPC schema as a description of this service",
      "result": {
        "name": "OpenRPC Schema",
        "schema": {
          "$ref": "https://raw.githubusercontent.com/open-rpc/meta-schema/master/schema.json"
        }
      }
    }
  ]
}

Примеры

Примеры документов OpenRPC можно найти в OpenRPC Examples. Должен быть пример, который использует каждую концепцию спецификации. Эти примеры должны быть использованы в качестве основы тестирования для всех официальных инструментов OpenRPC.

Объект OpenRPC

Это корневой объект документа OpenRPC. Содержимое этого объекта представляет собой целый документ OpenRPC. То, как этот объект создается или хранится, выходит за рамки спецификации OpenRPC.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект информации (Info Object)

Объект предоставляет метаданные об API. Метаданные МОГУТ быть использованы клиентами, если это необходимо, и МОГУТ быть представлены в инструментах редактирования или создания документации для удобства.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект контакта (Contact Object)

Контактная информация для открытого API.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект лицензии (License Object)

Информация о лицензии для открытого API.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект сервера (Server Object)

Объект описывающий сервер.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект переменных сервера (Server Variable Object)

Объект, представляющий серверную переменную для замены шаблона URL-адреса сервера.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект метода (Method Object)

Описывает интерфейс для данного имени метода. Имя метода используется в качестве поля метода тела JSON-RPC. Поэтому он ДОЛЖЕН быть уникальным.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект дескриптора содержимого (Content Descriptor Object)

Дескрипторы контента - это объекты, которые делают то, что они предлагают- описывают контент. Это многоразовые способы описания параметров или результата. Они ДОЛЖНЫ иметь схему.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект схемы (Schema Object)
Объект схемы позволяет определять типы входных и выходных данных. Объекты схемы ДОЛЖНЫ соответствовать описанию спецификаций JSON Schema Specification 7, каждый раз, когда объект схемы может использоваться, вместо него может использоваться "Ссылочный объект". Это позволяет ссылаться на определения, а не определять их повторно (inline).

Объект парного примера (Example Pairing Object)

Объект примера состоит из набора параметров примера и результата. Результат-это то, что вы можете ожидать от службы JSON-RPC, учитывая точные параметры.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект примера (Example Object)

Объект примера - это объект, определяющий пример, который должен соответствовать заданной "Схеме дескриптора содержимого". Если "Схема дескриптора содержимого" включает "examples", значение из этого примера объекта заменяет значение примера схемы.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект ссылки (Link Object)

Объект ссылки представляет собой возможную ссылку проектирования для результата. Наличие ссылки не гарантирует способность вызывающего абонента успешно вызывать ее, скорее она обеспечивает известную связь и механизм обхода между результатами и другими методами.

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

Для вычисления ссылок и предоставления инструкций, а так же для их выполнения "выражение выполнения" используется для доступа к значениям в методе и использования их в качестве параметров при вызове связанного метода.

Связанный метод должен быть идентифицирован непосредственно и должен существовать в списке методов, определенных объектом Methods.

Когда выражение среды выполнения не выполняется, целевому методу не передается значение параметра.

Значения из результата могут использоваться для управления связанным методом.

Клиенты переходят по всем ссылкам по своему усмотрению. Ни разрешения, ни возможность успешного вызова этой ссылки не гарантируется исключительно существованием отношения.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Выражение выполнения (Runtime Expression)

Выражения выполнения позволяют пользователю определить выражение, которое будет вычисляться в строку, как только будут известны желаемые значения. Они используются, когда желаемое значение ссылки или сервера может быть создано только во время выполнения. Этот механизм используется "Объектами ссылок" и "Переменными сервера".

Выражение времени выполнения использует синтаксис языка шаблонов JSON.

В таблице ниже приведены примеры выражений времени выполнения и примеры их использования в значении:

в документации таблица отсутствует

Выражения времени выполнения сохраняют тип ссылочного значения.

Объект ошибки (Error Object)

Определяет ошибку уровня приложения.

Объект компоненты (Components Object)

Содержит набор повторно используемых объектов для различных аспектов OpenRPC. Все объекты, определенные в объекте components, не будут влиять на API, если на них явно не ссылаются свойства вне объекта components.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Все фиксированные поля, объявленные выше, являются объектами, которые ДОЛЖНЫ использовать ключи, соответствующие регулярному выражению: "^[a-zA-Z0-9\.\-_]+$"

Объект тега (Tag Object)

Добавляет метаданные к одному тегу, который используется "Объект метода". Не обязательно иметь объект тега для каждого тега, определенного в экземплярах объекта метода.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект внешней документации (External Documentation Object)

Позволяет ссылаться на внешний ресурс для расширенной документации.

Этот объект МОЖЕТ быть расширен с помощью расширений спецификации.

Объект ссылки

Простой объект, позволяющий ссылаться на другие компоненты спецификации, внутренние и внешние.

Ссылочный объект определяется схемой JSON и следует той же структуре, поведению и правилам.

Этот объект не может быть расширен дополнительными свойствами, и любые добавленные свойства должны игнорироваться.

Расширения спецификации

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

Свойства расширений реализуются в виде шаблонных полей, которые всегда имеют префикс "x-".

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

Благодарю за внимание.