Вопрос по json, idl, rest, rpc, protocol-buffers – IDL для интерфейса JSON REST / RPC

13

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

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

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

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

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

Если вам действительно нужно использовать существующее решение, я бы просто использовал json-schema, которая кажется достаточно простой в использовании. В противном случае я не думаю, что слишком сложно самостоятельно проверить структуру JSON - убедитесь, что у каждого объекта есть нужные вам свойства, и сделайте это рекурсивно, если у вас тоже. В отличие от XML, JSON довольно прост в проверке, поэтому может быть и не существует подходящего решения для проверки схемы. this.lau_

Ваш Ответ

4   ответа
3

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

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

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

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

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

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

DLL doesn't have to be explicitly tied to any particular data representation format or built around it. Instead, such language can be fairly universal and cover wide range of practical use-cases (e.g. cross-language data serialization and data validation) and data formats (e.g. JSON, XML, Protocol Buffers).

IDL for RPC-style communication can be implemented as a thin, mostly syntactic layer on top of the universal DDL.

Such IDL and interface specifications can be transport agnostic.

Говоря об API в стиле REST через HTTP по сравнению с API в стиле RPC через HTTP.

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

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

0

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

7

I am not a believer in schemas as an alternative to input validation. There are properties that cannot be verified from the syntax. I think that was one of the ways that XML went wrong.

If your formats are too complex, then I would look at simplifying them.

2

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

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

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

Чтобы поддерживать больше имен пользователей:

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

Намного проще сделатьwithout breaking existing clients используя XML. JSON это сложно.

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

Похожие вопросы