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

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

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

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

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

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

Ответ 1

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

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

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

Ответ 2

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

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

Итак, да, в теории вы смотрите в правильном направлении. Однако на данный момент 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 не должна быть явно привязана к какому-либо определенному формату представления данных или построена вокруг него. Вместо этого такой язык может быть довольно универсальным и охватывать широкий спектр практических случаев использования (например, сериализация данных на разных языках и проверка данных) и форматы данных (например, JSON, XML, протокольные буферы).
IDL для связи в стиле RPC может быть реализована как тонкий, в основном синтаксический слой поверх универсального DDL.
Такие спецификации IDL и интерфейса могут быть транспортными агностиками.

Говоря о API-интерфейсах типа REST через HTTP по сравнению с API-интерфейсами RPC через HTTP.

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

В случае API-интерфейсов типа REST люди попадают в беду без уважительной причины. Теперь у них есть много другого материала для проверки: произвольно сложный синтаксис URL, включая динамические параметры, закодированные в сегментах URL (для всех методов HTTP) и строку запроса URL (только для метода HTTP GET), соответствие HTTP-методу (должен ли он быть GET, POST, PUT, DELETE и т.д.), Тело HTTP, когда некоторые параметры идут туда (иногда они делают это вручную дважды для параметров, представленных в JSON и XML), пользовательских заголовков HTTP и отдельно - служебную документацию. Представьте, что 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 (XML) с использованием Консолидации контента.

Ответ 4

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