IDL для интерфейса REST/RPC JSON

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

со всеми этими веб-API JSON дни, я бы надеялся на общее решение, но мне трудно найти его. Я заглянул в в JSON-схемы который является схемой проверки json, но и проект IETF и реализации кажутся довольно незрелыми (хотя они были вокруг некоторое время, что не является хорошим знаком).

несколько иной подход предлагается Протокол Буферы и Apache Avro, где схема не используется для проверки, но на самом деле требуется для кодирования/декодирования сообщения. Из этих 2 Avro, похоже, имеет довольно ограниченную документацию и реализации. ProtoBuf кажется лучше, но я не уверен, что это действительно подходит для использования в браузере для вызова JSON api?

теперь я начинаю сомневаться, смотрю ли я на это под прямым углом. Есть ли другие методы, доступные для того, чтобы сделать мой API немного более сильным? Или это формальное описание API JSON REST/RPC, которое побеждает цель с помощью JSON?

Edit: через 6 месяцев после этой темы мы нашли мангуста, что очень близко к тому, что мы искали.

13
idl json protocol-buffers rest rpc

4 ответов

Ниже Ответ, который я получил по электронной почте от Дугласа Крокфорда.

Я не верю в схемы как альтернативу проверке ввода. Есть свойства,которые нельзя проверить с помощью синтаксиса. Я думаю это был один из способов, которым XML пошел не так.

Если ваши форматы слишком сложны, то я бы посмотрел на упрощение их.

6

такие системы существуют, и я автор одной из них. Она называется Piqi-RPC и он выполняет проверку входных и выходных параметров на основе IDL для API в стиле RPC через HTTP.

Он поддерживает буферы протокола JSON, XML и Google в качестве форматов представления данных для ввода и вывода запросов HTTP POST. Клиенты могут выбрать любой из трех форматов и указать свой выбор, используя стандарт Accept и Content-Type заголовки HTTP.

Так, да, теоретически, вы смотрите в правильном направлении. Однако на данный момент Piqi-RPC поддерживает запись серверов только в Erlang, и это не будет очень полезно для вас, если вы используете другой стек. Я слышал, что Apache Thrift также поддерживает JSON через HTTP-транспорт, но я не проверял. Другой вид подобной системы, о которой я знаю (также для Эрланга), называется церковь ubf. Я слышал о библиотеках для Java, которые могут анализировать и проверять JSON на основе спецификации буферов протокола (например, http://code.google.com/p/protostuff/).

сама идея далека от новизны, но на практике не так много систем, которые подходят к ней. Это сложная проблема.

исторически IDLs использовались для определения интерфейса и сериализации двоичных данных, а не для проверки форматов динамического обмена данными (например, XML и JSON), которые появились позже. Sun-RPC IDL и CORBA IDL относятся к первой категории. WSDL будет одним из немногих примеров охватывая обе области, но это ужасная технология, и это был бы плохой выбор для большинства современных систем. Кроме того, существует много языков схем (также известных как DDLs -- Data definition languages), большинство из которых являются узкоспециализированными и работают только с одним форматом представления, например XML или JSON-схемы. Немногие из них имеют стабильные реализации.

на проект Piqi и Piqi-RPC, который основан на нем, строятся вокруг нескольких довольно простых реализации:

  • DLL не должен быть явно привязан к какому-либо конкретному формату представления данных или построен вокруг него. Вместо этого такой язык может быть достаточно универсальным и охватывать широкий спектр практических случаев использования (например, межязыковая сериализация данных и проверка данных) и форматов данных (например, JSON, XML, буферы протоколов).

  • IDL для связи в стиле RPC может быть реализован как тонкий, в основном синтаксический слой поверх универсальный DDL.

  • такие спецификации IDL и интерфейса могут быть агностиком перехода.

говоря о Rest-style API по HTTP по сравнению с RPC-style API по HTTP.

С API в стиле RPC разработчик службы или автоматизированная система должны проверить три вещи: имя функции (в соответствии с некоторой схемой именования службы), ввод и, если вы выберете так, вывод.

в случае API в стиле REST люди попадают в неприятности без причины. Теперь у них есть много материал для проверки: произвольно сложный синтаксис URL, включая динамические параметры, закодированные в сегментах URL (для всех методов HTTP) и строку запроса URL (только для метода HTTP GET), соответствие метода HTTP (должно ли это быть GET, POST, PUT, DELETE и т. д.), Тело HTTP, когда некоторые параметры идут туда (иногда они делают это вручную дважды для параметров, представленных в JSON и XML), пользовательские заголовки HTTP и отдельно -- service документация. Представьте себе, что IDL поддерживает все это!

3

XML лучше для RESTful услуг во многих отношениях. Он имеет родную связь (<link href= для всех HATEOAS вентиляторы), поддержка родного языка (lang="en") и отличная экосистема.

это также лучше для будущих проверок и будущих рефакторингов API. Преобразование этого:

<profile>
    <username>alganet</username>
</profile>

для поддержки большего количества Логинов:

<profile>
    <username>alganet</username>
    <username>alexandre</username>
</profile>

гораздо проще сделать без нарушения существующих клиентов использование XML. JSON тяжело на этом.

Если вам действительно нужен JSON, JSON-Schema-это путь. Это незрело, но я не знаю ничего лучше по этому делу. Возможно, ваши потребители могут выбирать между XML и JSON, поэтому они могут выбирать между небольшой полезной нагрузкой (JSON) или RESTful candies (XML), используя согласование контента.

2

Я бы сказал, что ответ на ваш последний вопрос-да. Если вам нужен способ ограничить и документировать "схему" JSON, почему вы не пошли с XML в первую очередь? Это не так уж сложно разобрать, и возможность применить схему для этого является большим преимуществом.

0