Привет мир! Меня зовут С., и я руководитель отдела роста здесь, в Wundergraph. Статья написана нашим генеральным директором / техническим директором Йенсом Нойсе. Наслаждаться!

GraphQL известен как язык запросов к графам запросов. Сегодня я хотел бы показать вам необычный вариант использования языка запросов: создание JSON API с проверкой JSON-Schema.

Внедрение серверов GraphQL и использование клиентов GraphQL для запросов к ним становится скучным, не так ли? Как насчет того, чтобы попробовать что-то новое? Как насчет кроссовера между OpenAPI, JSON-Schema и GraphQL?

Звучит интересно? Я надеюсь, что это так. Давай сделаем это!

Как некоторые, возможно, знают, я большой поклонник Persisted GraphQL Operations. Я не считаю, что серверы GraphQL должны напрямую раскрывать свой API. Я продолжаю писать на эту тему, например, я думаю, что GraphQL не предназначен для показа через Интернет. Кроме того, сохраняемые операции очень помогают с управлением версиями и обеспечением обратной совместимости API. В другой раз я говорил о том, что произойдет, если мы угрожаем операции GraphQL как схеме API. В этом посте я перечислил 13 уязвимостей безопасности GraphQL и то, как Persisted Operations помогают их решить.

Наконец, я много писал о слиянии GraphQL, REST, JSON-Schema и HTTP2. Проблема в том, что я понял, что этот пост в блоге был слишком длинным.

Итак, вот я и пишу более короткую статью с немного большим вниманием. Извините за паузу с обратными ссылками, SEO-хаки…

Итак, несколько фактов о сохраняемых операциях GraphQL.

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

Таким образом, сохраняемая операция GraphQL — это функция, которая может принимать несколько аргументов и возвращать объект JSON.

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

Этот пост не о безопасности или авторизации, а также не о том, как мы поддерживаем OpenID Connect, внедрение утверждений и т. д. Если вас интересуют такие вещи, вот документы по директиве @fromClaim.

В этом посте мы проигнорируем магию директивы @fromClaim.

Если мы сохраним эту операцию на сервере, мы можем превратить ее в следующую функцию.

Как видите, это функция, которая принимает ввод и возвращает ответ. И ввод, и ответ могут быть выражены как объект JSON.

Для ответа это очевидно. GraphQL возвращает JSON. Позвольте мне объяснить часть переменных.

Переменные GraphQL могут быть предоставлены «встроенными», то есть как часть операции/документа GraphQL. Если мы удаляем все переменные GraphQL, они «должны» предоставляться как объект JSON.

WunderGraph выполняет деинлайнинг по умолчанию, что подводит нас к важному выводу.

A Persisted GraphQL Operation is a function that takes a JSON Object and returns a JSON Object.

Функция с такой спецификацией на самом деле очень полезна!

Если мы пройдемся по AST этой операции GraphQL, мы сможем извлечь точную структуру JSON как для ввода, так и для ответа. Реализация graphql-js имеет отличную реализацию посетителя, что делает это довольно легко.

Если мы знаем структуру JSON, мы можем сделать еще один шаг вперед. Мы можем создать JSON-схему для ввода и ответа!

Это то, что мы делаем автоматически, поэтому давайте посмотрим на сгенерированные JSON-схемы!

Во-первых, входная схема.

Входные данные для нашей операции — это объект JSON только с одним свойством — сообщением. Обратите внимание, что поля name и email отсутствуют во входных данных. Это потому, что пользователю не разрешено вводить их, мы внедряем их, используя заявления пользователей OpenID Connect, но это другая тема. Важно то, что шаблон регулярного выражения был применен к сообщению, дополнительные свойства не разрешены, а сообщение является обязательным, потому что определение переменной String!, челка означает обязательное.

Во-вторых, схема ответа:

Схема ответа менее крутая. Операции GraphQL возвращают JSON, поэтому мы можем сопоставить все поля операции с JSON-схемой, пройдя через AST операции.

С этими определениями JSON-Schema мы теперь можем запускать генераторы кода для любого языка, TypeScript, Java, Go, Rust и т. д. и создавать клиентов TypeSafe.

Нравится эта статья?

Получайте сообщения из нашего блога прямо в свой почтовый ящик с помощью нашей рассылки подпишитесь!

Преимущества использования JSON API с JSON-Schema по сравнению с GraphQL

Мы извлекли важный урок из спецификации OpenAPI: JSON-Schema мощна! JSON-Schema — это стандарт для определения схемы для JSON, он хорошо поддерживается и имеет множество полезных точек интеграции.

Использование схемы JSON для проверки ввода на стороне сервера

JSON-Schema можно использовать для проверки входных данных на стороне сервера. Есть реализации на многих языках, которые делают это, WunderGraph использует реализацию Go, так как наш движок написан на Go.

Использование схемы JSON для создания форм

Существуют также такие инструменты, как React JSON Schema Form, которые позволяют создавать формы React из схемы JSON. Мы создали тесную интеграцию с WunderGraph с этой возможностью. Это позволяет вам создавать формы, просто написав операцию GraphQL, можно сгенерировать все, начиная с бэкэнда и заканчивая проверкой как на клиенте, так и на сервере. Этот подход очень удобен для разработчиков и экономит много времени. Все, что вам нужно сделать, это подключить серверную часть и настроить пользовательский интерфейс.

JSON API перед GraphQL делает его совместимым с Интернетом и позволяет избежать привязки к поставщику.

Еще одно преимущество использования JSON API по сравнению с GraphQL заключается в том, что каждая операция получает свой собственный уникальный URL-адрес. В сочетании с тем фактом, что запросы используют метод HTTP GET, а мутации используют HTTP POST, мы снова делаем GraphQL совместимым с Интернетом.

Под совместимостью я подразумеваю, что вы можете использовать существующую инфраструктуру Интернета, такую ​​как браузеры, кэши, CDN, прокси и т. д.

Отправка запросов READ через HTTP POST нарушает большую часть сетевой инфраструктуры. Если вместо этого мы используем GET для чтения и POST для записи, все в порядке.

Вы можете поставить Varnish, NginX или Cloudflare перед JSON API, и он просто работает, не требует дополнительной настройки, не привязывается к проприетарному механизму кэширования.

JSON API может быть понят Почтальоном

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

Тем не менее, даже не будучи полностью RESTful, он достаточно близок, чтобы его можно было использовать аналогичным образом.

Вот почему мы добавили небольшое изменение в наш Генератор кода с большим влиянием. Каждое приложение WunderGraph автоматически создает коллекцию Postman!

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

JSON API перед GraphQL повышает безопасность

В другом сообщении в блоге я написал о 13 наиболее распространенных уязвимостях в API GraphQL. Если мы поместим JSON API перед нашим виртуальным GraphQL API, мы устраним все проблемы, связанные с языком запросов. Добавляя сверху проверку JSON-Schema, мы добавляем дополнительный уровень безопасности для проверки ввода.

Вывод

Как мы уже говорили, добавление JSON API с JSON-Schema перед вашим GraphQL API имеет много преимуществ, но это еще не все.

Я не рассматриваю GraphQL как простой язык запросов, где вы создаете сервер, добавляете клиента и заканчиваете работу.

Описанный выше подход — это самый быстрый способ реализовать Backend For Frontend (BFF) на лету.

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

GraphQL как ORM для ваших API, уровень оркестровки API.

В настоящее время вы можете использовать REST, GraphQL, Apollo Federation (с подписками), PostgreSQL и MySQL в качестве источника данных для вашего приложения WunderGraph. WunderGraph объединяет все источники данных в один унифицированный «виртуальный график», который затем можно безопасно представить как JSON API, написав операции GraphQL.

Это все, что вам нужно для создания BFF.

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

В будущем вы сможете легко заменять источники данных, например. замените PostgreSQL на MySQL, переключитесь с REST на gRPC API и т. д., и все это без нарушения контракта JSON API.

Узнайте больше о других функциях, которые мы предоставляем и попробуйте их на своем локальном компьютере!

Если вам нужны более продвинутые примеры, взгляните на этот с использованием API-интерфейсов Apollo Federation и REST или на этот пример с приложением для чата в реальном времени поверх PostgreSQL.

Хотите попробовать Wundergraph для своей компании?

Давай поболтаем!"