Язык API

MONO — это программный комплекс для управления кооперативом. Он может использоваться полностью, включая терминальные интерфейсы и их расширения, либо частично, когда MONO выполняет роль бэкенда для внешних интерфейсов взаимодействия с пайщиками.

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

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

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

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

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

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

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

И еще один аргумент почему GraphQL-API - с ним нам нет необходимости держать отдельные технологии для обмена информацией в реальном времени. Используя подписки GraphQL-API, сервер 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 {
      # Укажите нужные поля схемы
    }
    provider_account {
      # Укажите нужные поля схемы
    }
    participant_account {
      # Укажите нужные поля схемы
    }
    user_account {
      # Укажите нужные поля схемы
    }    
  }
}

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

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

Запускаете запрос — и в ответе получите только те поля, которые запросили. Если появится ошибка о недостатке прав, убедитесь, что ваш пользователь имеет требуемую роль (например, 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
  }
}

И передаём переменные:

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

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

Подписки¶

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