Язык API

Всё взаимодействие между компонентами MONO осуществляется через GraphQL-API. Он предоставляет язык запросов и среду их выполнения, позволяя клиентам запрашивать только необходимые данные и минимизируя избыточную передачу информации. Кроме того, единая схема API объединяет в себе все сервисы, включая запросы, мутации и подписки на данные как самого приложения MONO, так и его расширений.

Преимущества¶

Язык запросов GraphQL-API позволяет сократить количество отдельных методов на бэкенде MONO, которые обычно предназначены для получения или обновления информации о небольших аспектах одной рабочей сущности. В традиционном подходе количество методов API и сопутствующего кода постоянно растёт, но полезная нагрузка каждого вызова становится всё меньше. GraphQL решает эту проблему, предоставляя единую схему запросов, которая позволяет клиенту определять только те данные, которые ему действительно нужны.

Язык GraphQL-API позволяет объединить все внутренние и внешние сервисы (включая сторонние) в единую конечную точку. Это упрощает интеграцию сервисов, даже если они написаны на разных языках программирования, и создаёт единую динамичную документацию, которая автоматически обновляется в реальном времени на основе схем объектов из программного кода.

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

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

Для работы с запросами, мутациями и подписками достаточно одного SDK-клиента, который создаётся на основе схем GraphQL-API с использованием GraphQL-zeus. Такой подход обеспечивает доступ ко всем сервисам, подключённым к GraphQL-API, и предоставляет автогенерируемый клиент с высокой типизацией и связностью данных. Это упрощает интеграцию и сокращает количество ошибок при разработке.

Кроме того, GraphQL-API исключает необходимость внедрения дополнительных технологий для обмена данными в реальном времени. Подписки GraphQL позволяют серверу MONO отправлять обновления клиенту с использованием встроенных возможностей, таких как WebSocket, без дополнительных решений.

Таким образом, GraphQL-API объединяет в себе обработку запросов, мутаций и подписок, заменяя собой отдельные инструменты и технологии, что делает его универсальным решением для разработки и интеграции.

Как с этим работать¶

GraphQL — это язык запросов и среда выполнения, позволяющие клиентам получать только те данные, которые нужны, и тем самым снижать лишнюю передачу информации. В MONO все операции — чтение (queries), запись (mutations) и подписки (subscriptions) — описаны в единой схеме, доступной через GraphQL-API. Эта схема объединяет сервисы самого MONO и всех его расширений.

В GraphQL все входные и выходные данные описаны типами в схемах. Если у поля или аргумента есть ! (например, String!), значит это поле обязательное и не может быть null. Если в схеме просто String, значит поле необязательное. Благодаря такому типизированному описанию вы чётко знаете, какие данные ожидаются на вход и какие поля можно запросить на выходе.

Playground¶

Для удобства тестирования рекомендуется применять playground, например, Altair.

Playground - это визуальный инструмент, где вы пишете и тестируете запросы, мутации, подписки. Справа находится вкладка Docs. В ней перечислены все доступные типы, поля и операции, а также их описания и требования к ролям для выполнения.

Также, вся документация ко всем запросам, мутациям и подпискам доступна по ссылке: GraphQL-API.

Запросы¶

Например, мы хотим извлечь информацию об аккаунте с помощью запроса getAccount. Ссылка на схему в документации 🔗 GraphQL API: Query.getAccount

Запрос getAccount, согласно схеме, возвращает объект Account, в котором есть следующие поля:

username: String! — имя аккаунта кооператива
blockchain_account: BlockchainAccount — системный аккаунт в блокчейне
participant_account: ParticipantAccount — пайщик кооператива
provider_account: MonoAccount — учётная запись провайдера
user_account: UserAccount — пользовательский аккаунт кооперативной экономики

Чтобы получить эти данные, в Playground можно написать:

query getAccountExample($username: String!) {
  getAccount(data: { username: $username }) {
    username
    blockchain_account {
      account_name

      # Укажите прочие нужные поля схемы
    }
    provider_account {
      username

      # Укажите прочие нужные поля схемы
    }
    participant_account {
      username

      # Укажите прочие нужные поля схемы
    }
    user_account {
      username

      # Укажите прочие нужные поля схемы
    }    
  }
}

Во вкладке Query Variables в Playground задайте:

{
  "username": "имя_аккаунта"
}

Все методы, которым требуется авторизацию ролью помечены в GraphQL-API соответствующей подписью, например: требуемые роли: 'chairman', что означает - только председатель может выполить вызов.

После отправки запроса, в ответе вы получите только те поля, которые запросили. Если появится ошибка о недостатке прав, убедитесь, что ваш пользователь имеет требуемую роль (например, chairman, member и т.п.).

Мутации¶

Для изменения или добавления данных GraphQL использует мутации. Например, мутация createDeposit создаёт объект платёжа паевого взноса. Ссылка на схему в документации 🔗 GraphQL API: Mutation.createDeposit

Пример:

mutation createDepositExample($username: String!, $quantity: String!) {
  createDeposit(data: { 
    username: $username
    quantity: $quantity
  }) {
    id
    amount
    status
    data
    # любые другие поля Payment
  }
}

И передаём переменные через Variables в Playground:

{
  "username": "voskhod",
  "quantity": "100.00 RUB"
}

Результат вернёт новый объект Payment, поля которого мы выбрали (id, amount, status, data)

Подписки¶

Подписка на изменение тех или иных параметров системы осуществляется аналогично запросам и мутациям. Они позволяют получать обновления в реальном времени, например, когда статус платежа меняется. Структура подписки схожа с запросом, только начинается словом subscription.