REST API v2

Все функции, доступные в программном клиенте Molis, включая аутентификацию, получение данных об экосистемах, обработку ошибок, оперирование с таблицами базы данных, страницами интерфейсов, запуск контрактов (транзакций сети) доступны через REST API платформы. Таким образом, благодаря REST API разработчики могут получить доступ ко всему функционалу платформы без использования программного клиента Molis.

Вызов команды происходит при обращении к /api/v2/command/[param], где command - имя команды, param - дополнительный параметр, например, имя изменяемого или получаемого ресурса. Отправлять параметры запросов следует с Content-Type: x-www-form-urlencoded. Ответ сервера представлен в JSON формате.

Обработка ошибок

В случае успешного выполнения запроса возвращается статус 200. В случае ошибки, кроме ошибочного статуса возвращается объект JSON c полями:

  • error - идентификатор ошибки,
  • msg - текст ошибки,
  • params - массив дополнительных параметров ошибки, которые могут быть подставлены в сообщение об ошибке.

Пример ответа

400 (Bad Request)
Content-Type: application/json
{
    "err": "E_INVALIDWALLET",
    "msg": "Wallet 1111-2222-3333 is not valid",
    "params": ["1111-2222-3333"]
}

Список ошибок

  • E_CONTRACT - There is not %s contract,
  • E_DBNIL - DB is nil,
  • E_ECOSYSTEM - Ecosystem %d doesn’t exist,
  • E_EMPTYPUBLIC - Public key is undefined,
  • E_EMPTYSIGN - Signature is undefined,
  • E_HASHWRONG - Hash is incorrect,
  • E_HASHNOTFOUND - Hash has not been found,
  • E_HEAVYPAGE - This page is heavy,
  • E_INSTALLED - platform is already installed,
  • E_INVALIDWALLET - Wallet %s is not valid,
  • E_LIMITTXSIZE - The size of tx is too big (%d),
  • E_NOTFOUND - Content page or menu has not been found,
  • E_NOTINSTALLED - platform is not installed. В этом случае нужно запустить установку командно install,
  • E_PARAMNOTFOUND - parameter has not been found,
  • E_QUERY - DB query is wrong,
  • E_RECOVERED - API recovered, возвращается в случае panic error,
  • E_SERVER - Server error. Возвращается в случае ошибки в библиотечных функциях golang; поле msg содержит текст ошибки,
  • E_SIGNATURE - Signature is incorrect,
  • E_STATELOGIN - %s is not a membership of ecosystem %s,
  • E_TABLENOTFOUND - Table %s has not been found,
  • E_TOKEN - Token is not valid,
  • E_TOKENEXPIRED - Token is expired by %s,
  • E_UNAUTHORIZED - Unauthorized,
  • E_UNDEFINEVAL - Value %s is undefined,
  • E_UNKNOWNUID - Unknown uid,
  • E_OBSCREATED - Off-Blockchain Server is already created.

Если, неважно где, возвращается ошибка E_RECOVERED, то это баг, который требует обнаружения и исправления. Ошибка E_NOTINSTALLED должна возвращаться любой командой кроме install, в случае, если система еще не установлена. Ошибка E_SERVER теоретически может возвратится в любой команде. Если она возникает на неверных входных параметрах, то её можно заменить на соответствующие ошибки. В противном случае, это ошибка сообщает о неверном функционировании или настройке системы, то есть требует более детального изучения. Ошибка E_UNAUTHORIZED может возвращаться на любой команде кроме install, getuid, login в случае, если не был осуществлен login или сессия закончилась.

Маршруты недоступные в OBS

txstatus
txinfo
txinfoMultiple
appcontent
appparam
appparams
history
balance
block
maxblockid
ecosystemparams
ecosystemparam
systemparams

Аутентификация

Для аутентификации используется JWT токен http://www.jwt.org. После получения JWT токена необхоимо передавать его при каждом запросе в заголовке: Authorization: Bearer TOKEN_HERE.

getuid

GET/ Возвращает уникальное значение, которое нужно подписать своим приватным ключом и отправить обратно серверу с помощью команды login. На данный момент создается временный JWT токен, который нужно передать в Authorization при вызове login.

GET
/api/v2/getuid

Ответ

  • uid - строка для подписи.
  • token - временный токен для передачи в login. Время жизни временного токена сейчсас составляет 5 секунд.
  • network_id - идентификатор NetworkID сервера.

В случае, когда авторизация не требуется, то возвращаются

  • expire - количество секунд до истечения срока,
  • ecosystem - идентификатор экосистемы,
  • key_id - идентификатор кошелька,
  • address - адрес кошелька в формате XXXX-XXXX-.....-XXXX.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "uid": "28726874268427424",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6I........AU3yPRp64SLO4aJqhN-kMoU5HNYTDplQXbVu0Y",
    "network_id": "5324976953280995276"
}

Ошибки: E_SERVER

login

POST/ Аутентификация пользователя. Предварительно необходимо вызвать команду getuid для получения уникального значения и подписать его. В заголовке нужно передать временный JWT токен полученный вместе с getuid. В случае успешного завершения нужно полученный в ответе токен передавать во всех запросах в заголовке Authorization.

Запрос

POST
/api/v2/login
  • [ecosystem] - идентификатор экосистемы. Если не указан, то берется первая экосистема,
  • [expire] - время длительности JWT токена в секундах, по умолчанию - 36000,
  • [pubkey] - публичный ключ hex; если в блокчейне уже есть хранится ключ, то нужно передать идентификатор аккаунта в любом виде в параметре key_id,
  • [key_id] - идентификатор аккаунта в виде числа или XXXX-...-XXXX; использовать, если публичный ключ уже хранится в блокчейне; нельзя указывать совместно с pubkey,
  • signature - подпись uid полученного через getuid hex.

Ответ

  • token - JWT токен,
  • ecosystem - идентификатор экосистемы,
  • key_id - идентификатор аккаунта,
  • address - адрес аккаунта в формате XXXX-XXXX-.....-XXXX,
  • notify_key - ключ для получения уведомлений,
  • isnode - true или false - является ли владельцем данной ноды,
  • isowner - true или false - является ли владельцем данной экосистемы,
  • obs - true или false - есть ли у экосистемы virtual dedicated ecosystem.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6I........AU3yPRp64SLO4aJqhN-kMoU5HNYT8fNGODp0Y"
    "ecosystem":"1",
    "key_id":"12345",
    "address": "1234-....-3424"
}

Ошибки: E_SERVER, E_UNKNOWNUID, E_SIGNATURE, E_STATELOGIN, E_EMPTYPUBLIC

Служебные команды

network

GET/ Возвращает информацию о текущей сети, включая список нод. Не требует авторизации.

GET
/api/v2/network

Ответ

  • network_id - идентификатор сети,
  • centrifugo_url - адрес сентрифуги,
  • test - равно true, если сеть работает в тестовом режиме,
  • private - равно true, если это частная сеть,
  • full_nodes - массив нод.

Каждая нода описывает следующими параметрами

  • tcp_address - адрес TCP сервера,
  • api_address - адрес API сервера,
  • public_key - публичный ключ ноды,
  • public_key - публичный ключ ноды,
  • unban_time - Если нода забанена, то это время, до которого действует запрет,
  • stopped - равно true, если нода остановлена.

Вариант ответа

200 (OK)
Content-Type: application/json
{
     "network_id":"1",
     "centrifugo_url":"http://127.0.0.1:8000",
     "test":true,
     "private":false,
     "full_nodes": [
          {"tcp_address":"http://mysite.com:7080",
           "api_address":"http://mysite.com:7079",
           "public_key":"04c0b50....3ba20e",
           "unban_time":"",
           "stopped":false
          }
      ]
}

Ошибки: E_SERVER

version

GET/ Возвращает текущую версию сервера. Запрос доступен без авторизации.

Запрос

GET
/api/v2/version

Вариант ответа

200 (OK)
Content-Type: application/json
"0.1.6"

Функции получения данных

balance

GET/ Возвращает баланс указанного аккаунта в текущей экосистеме.

Запрос

GET
/api/v2/balance/{key_id}
  • key_id - идентификатор аккаунта, может быть представлен в любом формате - int64, uint64, XXXX-...-XXXX; поиск указанного аккаунта осуществляется в экосистеме, в которую вошел пользователь.

Ответ

  • amount - cумма на аккаунте в минимальных единицах,
  • money - cумма на аккаунте в единицах.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "amount": "123450000000000000000",
    "money": "123.45"
}

Ошибки: E_SERVER, E_INVALIDWALLET

blocks

GET/ Возвращает список блоков и их краткое содержимое. Запрос не требует авторизации.

Запрос

GET
/api/v2/blocks

Ответ

Номер блока

Для каждой транзакции в блоке: * hash - Хеш транзакции * contract_name - имя контракта * params - массив, содержащий параметры контракта * key_id - для первого блока - ID ключа, которым подписан первый блок, иначе - ID ключа, подписавшего транзакцию.

Вариант ответа

200 (OK)
Content-Type: application/json
{"1":
    [{"hash":"PhHV1g7jUyDEwiETexBMLJPEwH4yEknCIIOAj43Dn4U=",
    "contract_name":"",
    "params":null,
    "key_id":-2157832554603111963}]
}

Ошибки: E_SERVER, E_NOTFOUND

detailed_blocks

GET/ Возвращает список блоков и расширенную информацию об их содержимом. Запрос не требует авторизации.

Запрос

GET
/api/v2/detailed_blocks

Ответ

Номер блока

  • header - содержимое заголовка блока, содержит следующие поля:
    • block_id - номер блока
    • time - время генерации блока
    • key_id - ID ключа подписавшего блок
    • node_position - номер ноды, сгенерировавшей блок
    • version - версия структуры блока
  • hash - хеш блока
  • node_position - номер ноды, сгенерировавшей блок
  • key_id - ID ключа, подписавшего блок
  • time - время генерации блока
  • tx_count - количество транзакций в блоке
  • rollback_hash - хеш транзакций в блоке
  • mrkl_root - хеш листа дерева Меркла, соответствующего данному блоку
  • bin_data - сериализованные заголовок блока; транзакции, вошедшие в блок; хеш предыдущего блока и приватный ключ ноды, сгенерировавшей блок
  • sys_update - в блоке есть транзакция, обновившая системные параметры убрать из апи
  • transactions - массив транзакций блока, каждая запись содержит следующие поля:
    • hash - хеш транзакции
    • contract_name - название конракта
    • params - массив параметров, переданных в контракт
    • key_id - ID ключа, подписавшего транзакцию
    • time - время генерации транзакции
    • type - тип транзакции

Вариант ответа

200 (OK)
Content-Type: application/json
{"1":
    {"header":
        {"block_id":1,
        "time":1545342081,
        "ecosystem_id":0,
        "key_id":3670289659738809576,
        "node_position":0,
        "sign":null,
        "hash":null,
        "version":1},
    "hash":"TjTSRXcyJNgCn8GHEu16S2CheO0IZglxKQa/4S/Xzw4=",
    "ecosystem_id":0,
    "node_position":0,
    "key_id":3670289659738809576,
    "time":1545342081,
    "tx_count":1,
    "rollbacks_hash":"47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
    "mrkl_root":"NWNhODNmZGRiYmZhNTk3OTc0MzI1ODY4YjFiNDM3NDU3NTliOGUyNThmODM0NjY1ZWExOTkwZGZjNTZjZjhlMg==",
    "bin_data":null,
    "sys_update":false,
    "gen_block":false,
    "stop_count":0,
    "transactions":[
        {"hash":"ZkGFY/WrvlsHXhZtpmodEoMX6MsBwF2Ji1G5Y7XgRjY=","contract_name":"","params":null,"key_id":0,"time":0,"type":0}]
    }
}

Ошибки: E_SERVER, E_NOTFOUND

/data/{table}/{id}/{column}/{hash}

GET/ Возвращает данные из ячейки, заданной таблицей, колонкой и id записи, в случае, если хеш данных совпадает с отправленным хешем, иначе возвращает ошибку. Запрос не требует авторизации.

Запрос

GET
/data/{table}/{id}/{column}/{hash}
  • table - название таблицы
  • id - id записи
  • column - имя колонки
  • hash - хеш запрашиваемых данных

Ответ

Бинарные данные

keyinfo

GET/ Возвращает список экосистем с ролями, где зарегистрирован данный ключ. Запрос не требует авторизации.

Запрос

GET
/api/v2/keyinfo/{key_id}
  • key_id - идентификатор аккаунта, может быть представлен в любом формате - int64, uint64, XXXX-...-XXXX; поиск указанного аккаунта осуществляется во всех экосистемах.

Ответ

  • ecosystem - идентификатор экосистемы,
  • name - наименование экосистемы,
  • roles - список ролей пользователя в этой экосистеме с полями id и «name».

Вариант ответа

200 (OK)
Content-Type: application/json
[{
     "ecosystem":"1",
     "name":"platform ecosystem",
     "roles":[{"id":"1","name":"Admin"},{"id":"2","name":"Developer"}]
}]

Ошибки: E_SERVER, E_INVALIDWALLET

Получение метрик

keys

GET/ Возвращает количество ключей

GET
/api/v2/metrics/keys

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "count": 28
}

blocks

GET/ Возвращает количество блоков

GET
/api/v2/metrics/blocks

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "count": 28
}

mem

GET/ Возвращает информацию об используемой памяти. Данный вызов доступен без авторизации.

GET
/api/v2/metrics/mem

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "alloc": 9608184,
    "sys": 72349944
}

transactions

GET/ Возвращает количество транзакций

GET
/api/v2/metrics/transactions

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "count": 28
}

ecosystems

GET/ Возвращает количество экосистем

GET
/api/v2/metrics/ecosystems

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "count": 28
}

fullnodes

GET/ Возвращает количество валидирующих нод

GET
/api/v2/metrics/fullnodes

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "count": 28
}

Работа с экосистемами

ecosystemname

GET/ Возвращает имя экосистемы по коду. Данный метод api не требует авторизации.

GET
/api/v2/ecosystemname?id=..
  • id - код экосистемы

Варианты ответа

200 (OK)
Content-Type: application/json
{
    "ecosystem_name": "platform_ecosystem"
}

Ошибки: E_PARAMNOTFOUND

appparams

GET/ Возвращает список параметров приложения в текущей или указанной экосистеме.

Запрос

GET
/api/v2/appparams/{appid}[?ecosystem=...&names=...]
  • [appid] - идентификатор приложения,
  • [ecosystem] - идентификатор экосистемы; если не указан, то будут возвращены параметры текущей экосистемы,
  • [names] - список получаемых параметров; при желании можно указать через запятую список имен получаемых параметров, например, /api/v2/appparams/1?names=name,mypar.

Ответ

  • list - массив, каждый элемент которого содержит следующие параметры.
    • name - наименование параметра,
    • value - значение параметра,
    • conditions - права на изменение параметра.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "list": [{
        "name": "name",
        "value": "MyState",
        "conditions": "true",
    },
    {
        "name": "mypar",
        "value": "My value",
        "conditions": "true",
    },
    ]
}

Ошибки: E_ECOSYSTEM

appcontent

GET/ Возвращает списки (id , название) для страниц, интерфейсных блоков и контрактов для заданного приложения.

Запрос

GET
/api/v2/appcontent/{appid}[?ecosystem=...]
  • [appid] - идентификатор приложения,
  • [ecosystem] - идентификатор экосистемы; если не указан, то будут возвращены параметры текущей экосистемы

Ответ

  • [list], [list], [list] - массив с описанием блоков интерфейса, массив с описанием страниц, массив с описанием контрактов. Каждый массив содержит элементы с полями:
    • id - наименование параметра,
    • name - значение параметра.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "blocks": [
        { "id": 1, "name": "admin_link" },
        { "id": 2, "name": "export_info" }
    ],
    "pages": [
        { "id": 1, "name": "admin_index" },
        { "id": 2, "name": "developer_index" }
    ],
    "contracts": [
        { "id": 1, "name": "AdminCondition" },
        { "id": 2, "name": "DeveloperCondition" }
    ]
}

Ошибки: E_ECOSYSTEM

appparam/{appid}/{name}

GET/ Возвращает информацию о параметре приложения c идентификатор {appid} и с именем {name} в текущей или указанной экосистеме.

Запрос

GET
/api/v2/{appid}/{appid}/{name}[?ecosystem=1]
  • appid - идентификатор приложения,
  • name - имя запрашиваемого параметра,
  • [ecosystem] - можно указать идентификатор экосистемы. По умолчанию, возвратится значение текущей экосистемы.

Ответ

  • id - идентификатор параметра,
  • name - наименование параметра,
  • value - значение параметра,
  • conditions - условие изменения параметра.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "id": "10",
    "name": "par",
    "value": "My value",
    "conditions": "true"
}

Ошибки: E_ECOSYSTEM,E_PARAMNOTFOUND

ecosystemparams

GET/ Возвращает список параметров экосистемы.

Запрос

GET
/api/v2/ecosystemparams/[?ecosystem=...&names=...]
  • [ecosystem] - идентификатор экосистемы; если не указан, то будут возвращены параметры текущей экосистемы,
  • [names] - список получаемых параметров; при желании можно указать через запятую список имен получаемых параметров, например, /api/v2/ecosystemparams/?names=name,currency,logo.

Ответ

  • list - массив, каждый элемент которого содержит следующие параметры.
    • name - наименование параметра,
    • value - значение параметра,
    • conditions - права на изменение параметра.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "list": [{
        "name": "name",
        "value": "MyState",
        "conditions": "true",
    },
    {
        "name": "currency",
        "value": "MY",
        "conditions": "true",
    },
    ]
}

Ошибки: E_ECOSYSTEM

ecosystemparam/{name}

GET/ Возвращает информацию о параметре с именем {name} в текущей или указанной экосистеме.

Запрос

GET
/api/v2/ecosystemparam/{name}[?ecosystem=1]
  • name - имя запрашиваемого параметра,
  • [ecosystem] - можно указать идентификатор экосистемы. По умолчанию, возвратится значение текущей экосистемы.

Ответ

  • name - наименование параметра,
  • value - значение параметра,
  • conditions - условие изменения параметра.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "name": "currency",
    "value": "MYCUR",
    "conditions": "true"
}

Ошибки: E_ECOSYSTEM,E_PARAMNOTFOUND

tables/[?limit=…&offset=…]

GET/ Возвращает список таблиц в текущей экосистеме. Можно указать смещение и количество запрашиваемых таблицы.

Запрос

  • [limit] - количество записей, по умолчанию - 25,
  • [offset] - смещение начала записей, по умолчанию - 0,
GET
/api/v2/tables

Ответ

  • count - общее количество записей в таблице,
  • list - массив, каждый элемент которого содержит следующие параметры:
    • name - имя таблицы, возвращается без префикса,
    • count - количество записей в таблице.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "count": "100"
    "list": [{
        "name": "accounts",
        "count": "10",
    },
    {
        "name": "citizens",
        "count": "5",
   },
    ]
}

table/{name}

GET/ Возвращает информацию о таблице с указанным именем в текущей экосистеме.

Возвращаются следующие поля: * name - имя таблицы, * insert - права на вставку элементов, * new_column - права на добавление клонки, * update - права на изменене прав, * columns - массив колонок с полями name, type, perm - имя, тип, права на изменение.

Запрос

GET
/api/v2/table/mytable
  • name - имя таблицы (без префикса-идентифкатора экосистемы)

Ответ

  • name - имя таблицы (без префикса-идентифкатора экосистемы),
  • insert - право на добавление записей,
  • new_column - право на добавление колонки,
  • update - право на изменение записей,
  • conditions - право на изменение настроек таблицы,
  • columns - массив информации о колонках:
    • name - имя столбца,
    • type - тип колонки; dозможны следующие значения: varchar, bytea, number, money, text, double, character,
    • perm - права на изменение записе в столбце.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "name": "mytable",
    "insert": "ContractConditions(`MainCondition`)",
    "new_column": "ContractConditions(`MainCondition`)",
    "update": "ContractConditions(`MainCondition`)",
    "conditions": "ContractConditions(`MainCondition`)",
    "columns": [{"name": "mynum", "type": "number", "perm":"ContractConditions(`MainCondition`)" },
        {"name": "mytext", "type": "text", "perm":"ContractConditions(`MainCondition`)" }
    ]
}

Ошибки: E_TABLENOTFOUND

list/{name}[?limit=…&offset=…&columns=]

GET/ Возвращает список записей указанной таблицы в текущей экосистеме. Можно указать смещение и количество запрашиваемых элементов таблицы.

Запрос

  • name - имя таблицы,
  • [limit] - количество записей, по умолчанию - 25,
  • [offset] - смещение начала записей, по умолчанию - 0,
  • [columns] - список запрашиваемых колонок через запятую; если не указано, то будут возвращены все колонки; колонка id возвращается в любом случае
GET
/api/v2/list/mytable?columns=name

Ответ

  • count - общее количество записей в таблице,
  • list - массив, каждый элемент которого содержит следующие параметры:
    • id - идентификатор записи,
    • columns - последовательность запрошенных колонок.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "count": "10"
    "list": [{
        "id": "1",
        "name": "John",
    },
    {
        "id": "2",
        "name": "Mark",
   },
    ]
}

Ошибки: E_TABLENOTFOUND

sections[?limit=…&offset=…&lang=]

GET/ Возвращает список записей таблицы sections в текущей экосистеме. Можно указать смещение и количество запрашиваемых элементов таблицы. При этом, если поле roles_access содержит список ролей и текущей роли там нет, то эта запись не будет возвращаться. Также, вданных столбца title происходит замена языковых ресурсов.

Запрос

  • [limit] - количество записей, по умолчанию - 25,
  • [offset] - смещение начала записей, по умолчанию - 0,
  • [lang] - можно указать двухбуквенный код языка или lcid, для подключения соответствующих языковых ресурсов. Например, en,ru,fr,en-US,en-GB. Если, например, не будет найден ресурс для en-US, то он будет искаться для en.
GET
/api/v2/sections

Ответ

  • count - общее количество записей в таблице,
  • list - массив, каждый элемент которого содержит все столбцы таблицы sections.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "count": "2"
    "list": [{
        "id": "1",
        "title": "Development",
        "urlpage": "develop",
        ...
    },
    ]
}

Ошибки: E_TABLENOTFOUND

row/{tablename}/{id}[?columns=]

GET/ Возвращает запись таблицы с указанным id в текущей экосистеме. Можно указать возвращаемые колонки.

Запрос

  • tablename - имя таблицы,
  • id - идентификатор записи,
  • [columns] - список запрашиваемых колонок через запятую, если не указано, то будут возвращены все колонки; колонка id возвращается в любом случае.
GET
/api/v2/row/mytable/10?columns=name

Ответ

  • value - массив полученных значений колонок:
    • id - идентификатор записи,
    • последовательность запрошенных колонок.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "values": {
    "id": "10",
    "name": "John",
    }
}

Ошибки: E_QUERY

row/{tablename}/{column}/{value}[?columns=]

GET/ Возвращает запись таблицы с указанным значением колонки в текущей экосистеме. Можно указать возвращаемые колонки.

Запрос

  • tablename - имя таблицы,
  • column - имя колонки,
  • value - значение колонки,
  • [columns] - список запрашиваемых колонок через запятую, если не указано, то будут возвращены все колонки; колонка id возвращается в любом случае.
GET
/api/v2/row/mytable/name/john?columns=name

Ответ

  • value - массив полученных значений колонок:
    • id - идентификатор записи,
    • последовательность запрошенных колонок.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "values": {
    "id": "10",
    "name": "John",
    }
}

Ошибки: E_QUERY

systemparams

GET/ Возвращает список системных параметров.

Запрос

GET
/api/v2/systemparams/[?names=...]
  • [names] - список получаемых параметров; при желании можно указать через запятую список имен получаемых параметров, например, /api/v2/systemparams/?names=max_columns,max_indexes.

Ответ

  • list - массив, каждый элемент которого содержит следующие параметры:
    • name - наименование параметра,
    • value - значение параметра,
    • conditions - права на изменение параметра.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "list": [{
        "name": "max_columns",
        "value": "100",
        "conditions": "ContractAccess("@0UpdSysParam")",
    },
    {
        "name": "max_indexes",
        "value": "1",
        "conditions": "ContractAccess("@0UpdSysParam")",
    },
    ]
}

history/{name}/{id}

GET/ Возвращает историю изменения записи указанной таблицы в текущей экосистеме.

Запрос

  • name - имя таблицы,
  • id - идентификатор записи.
GET
/api/v2/history/pages/1

Ответ

  • list - массив, каждый элемент которого содержит измененные параметры для запрашиваемой записи

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "list": [
        {
            "name": "default_page",
            "value": "P(class, Default Ecosystem Page)"
        },
        {
            "menu": "default_menu"
        }
    ]
}

interface/{page|menu|block}/{name}

GET/ Возвращает запись таблицы page, menu или block с указанным name в текущей экосистеме.

Запрос

  • name - название записи в указанной таблице.
GET
/api/v2/interface/page/default_page

Ответ

  • id - идентификатор записи,
  • name - название записи,
  • другие колонки таблицы.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "id": "1",
    "name": "default_page",
    "value": "P(Page content)",
    "default_menu": "default_menu",
    "validate_count": 1
}

Ошибки: E_QUERY, E_NOTFOUND

Функции работы с контрактами

contracts[?limit=…&offset=…]

GET/ Возвращает список контрактов в текущей экосистеме. Можно указать смещение и количество запрашиваемых контрактов.

Запрос

  • [limit] - количество записей, по умолчанию - 25,
  • [offset] - смещение начала записей, по умолчанию - 06.
GET
/api/v2/contracts

Ответ

  • count - общее количество записей в таблице,
  • list - массив, каждый элемент которого содержит следующие параметры:
    • id - идентификатор записи,
    • name - имя контракта,
    • value - исходный текст контракта,
    • active - равно «1», если контракт привязан к аккаунту, и «0» в противном случае,
    • key_id - аккаунт привязанный к контракту,
    • address - адрес аккаунта привязанного к контракту в формате XXXX-...-XXXX.
    • conditions - права на изменение контракта,
    • token_id - экосистема, в токенах которой оплачивается контракт.

Вариант ответа

  200 (OK)
  Content-Type: application/json
  {
      "count": "10"
      "list": [{
          "id": "1",
          "name": "MainCondition",
          "token_id":"1",
          "key_id":"2061870654370469385",
          "active":"0",
          "value":"contract MainCondition {
conditions {
    if(StateVal(`founder_account`)!=$citizen)
    {
        warning `Sorry, you dont have access to this action.`
      }
    }
  }",
  "address":"0206-1870-6543-7046-9385",
  "conditions":"ContractConditions(`MainCondition`)"
   },
  ...
    ]
  }

contract/{name}

GET/ Возвращает информацию о смарт конракте с именем {name}. По умолчанию, смарт контракт ищется в текущей экосистеме.

Запрос

  • name - имя смарт контракта.
GET
/api/v2/contract/mycontract

Ответ

  • id - идентификатор контракта в Виртуальной машине
  • name - имя смарт контракта с идентификатором экосистемы, например, @{idecosystem}name.
  • state - ID экосистемы, в которой создан контракт,
  • walletid - ID кошелька владельца контракта,
  • tokenid - токены, в которых производится оплата за контракт,
  • address - адрес аккаунта привязанного к контракту в формате XXXX-...-XXXX,
  • tableid - идентификатор записи в таблице contracts, где хранится исходный код контракта,
  • fields - массив, содержащий информацию о каждом параметре в разделе data контракта и содержит поля:
    • name - имя поля,
    • type - тип парметра,
    • optional - true если параметр опциональный и false в противном случае.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "fields" : [
        {"name":"amount", "type":"int", "optional": false},
        {"name":"name", "type":"string", "optional": true}
    ],
    "id": 150,
    "name": "@1mycontract",
    "tableid" : 10,
}

sendTx

POST/ Принимает транзакции, переданные в параметрах и складывает в очередь на обработку. В случае успешного выполнения возвращается хэш транзакции, c помощью которого можно получить номер блока в случае успешного выполнения или текст ошибки.

Запрос

  • any_key - содержимое транзакции, в качестве названия параметра может быть произвольным.

Метод поддерживает прием нескольких транзакций.

POST
/api/v2/sendTx

Заголовки:
Content-Type: multipart/form-data

Параметры:
tx1 - содержимое первой транзакции
txN - содержимое N-ой транзакции

Ответ

  • hashes - словарь с хешами отправленных транзакций
    • tx1 - hex хэш 1 транзакции;
    • txN - hex хэш N-ой транзакции.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "hashes": {
        "tx1": "67afbc435634.....",
        "txN": "89ce4498eaf7.....",
}

Ошибки: E_LIMITTXSIZE

txstatus/

POST/ Возвращает номер блока или ошибку отправленных транзакции с данными хэшами. Если возвращаемые значения blockid и errmsg пустые, значит транзакция еще не была запечатана в блок.

Запрос

  • data - json содержащий список хэшей проверяемых транзакций.
{"hashes":["contract1hash", "contract2hash", "contract3hash"]}
POST
/api/v2/txstatus/

Ответ

  • results - словарь содержащий в качестве ключа хэш транзакции а в качестве значения результат выполнения.

    hash - хэш транзакции

    • blockid - номер блока, в случае успешной обработки транзакции,
    • result - результат работы транзакции, возвращаемый через переменную $result,
    • errmsg - текст ошибки, в случае отклонения транзакции.

Вариант ответа

200 (OK)
Content-Type: application/json
{"results":
  {
    "hash1": {
         "blockid": "3123",
         "result": "",
     },
     "hash2": {
          "blockid": "3124",
          "result": "",
     }
   }
 }

Ошибки: E_HASHWRONG, E_HASHNOTFOUND

txinfo/{hash}

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

Запрос

  • hash - хэш проверяемой транзакции,
  • [contractinfo] - для получения информации о контракте и параметрах, укажите этот параметр со значением 1.
GET
/api/v2/txinfo/2353467abcd7436ef47438

Ответ

  • blockid - номер блока, в который попала транзакции. Если равен 0, то транзакция не найдена,
  • confirm - количество подтверждений данного блока,
  • data - если был указан параметр contentinfo, то здесь вернется json информация о контракте и параметрах.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "blockid": "4235237",
    "confirm": "10"
}

Ошибки: E_HASHWRONG

txinfoMultiple/

GET/ Возвращает инфоромацию о транзакциях с данными хэшами.

Запрос

  • data - json содержащий список хэшей проверяемых транзакций в виде шестнадцатеричных строк.
  • [contractinfo] - для получения информации о контракте и параметрах, укажите этот параметр со значением 1.
{"hashes":["contract1hash", "contract2hash", "contract3hash"]}
GET
/api/v2/txinfoMultiple/

Ответ

  • results - словарь содержащий в качестве ключа хэш транзакции а в качестве значения результат выполнения.

    hash - хэш транзакции

    • blockid - номер блока, вкоторый попала транзакции,
    • confirm - количество подтверждения данного блока,
    • data - если был указан параметр contentinfo, то здесь вернется json информация о контракте и параметрах.

Вариант ответа

200 (OK)
Content-Type: application/json
{"results":
  {
    "hash1": {
         "blockid": "3123",
         "confirm": "5",
     },
     "hash2": {
          "blockid": "3124",
          "confirm": "3",
     }
   }
 }

Ошибки: E_HASHWRONG

/page/validators_count/{name}

GET/ Возвращает количество нод валидации для страницы {name}

Запрос

  • name - имя страницы с префиксом экосистеме, в формате: @1page_name, где @1 указывает на индекс экосистемы
GET
/api/v2/page/validators_count/@1page_name

Ответ

  • validate_count - количество нод для валидации

Вариант ответа

200 (OK)
Content-Type: application/json
{"validate_count":1}

Ошибки: E_NOTFOUND, E_SERVER

content/{menu|page}/{name}

POST/ Возвращает JSON представление кода указанной страницы или меню с именем {name}, которое получается после обработки шаблонизатором. При запросе можно передавать дополнительные параметры, которые можно использовать в шаблонизаторе. Если страница или меню не найдены, то возвращается ошибка 404.

Запрос

  • menu|page - page или menu для получения страницы или меню соответственно,
  • name - имя получаемой страницы или меню,
  • [lang] - можно указать двухбуквенный код языка или lcid, для подключения соответствующих языковых ресурсов. Например, en,ru,fr,en-US,en-GB. Если, например, не будет найден ресурс для en-US, то он будет искаться для en.
  • [app_id] - ID приложения. Передается вместе с lang,т.к функции работающие с языком в шаблонизаторе не знают AppID. Передавать как число.
POST
/api/v2/content/page/default

Ответ

  • menu - имя меню для страницы при вызове content/page/…,
  • menutree - JSON дерево меню для страницы при вызове content/page/…,
  • title - заголовок для меню content/menu/…,
  • tree - JSON дерево объектов.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "tree": {"type":"......",
          "children": [
               {...},
               {...}
          ]
    },
}

Ошибки: E_NOTFOUND, E_SERVER, E_HEAVYPAGE

content/source/{name}

POST/ Возвращает JSON представление кода указанной страницы с именем {name} без выполнения функций и получения данных. Возвращаемое дерево соответствует шаблону страницы и может быть использовано в визуальном конструкторе. Если страница или меню не найдены, то возвращается ошибка 404.

Запрос

  • name - имя получаемой страницы.
POST
/api/v2/content/source/default

Ответ

  • tree - JSON дерево объектов.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "tree": {"type":"......",
          "children": [
               {...},
               {...}
          ]
    },
}

Ошибки: E_NOTFOUND, E_SERVER

content/hash/{name}

POST/ Возвращает SHA256 хэш-значение страницы с именем {name}. Если страница или меню не найдены, то возвращается ошибка 404. Данный метод api не требует авторизации. Так как метод не требует авторизации, то для того, чтобы получить правильный хэш при обращении к другим нодам, необходимо также передавать параметры, которые перечислены после name. Для получения страниц из других экосистем необходимо добавить префикс @(ecosystemId) к имени страницы. Например, @2mypage.

Запрос

  • name - имя получаемой страницы,
  • ecosystem - идентификатор экосистемы,
  • keyID - идентифкатор польлзователя,
  • roleID - идентификаторо роли пользователя,
  • isMobile - признак запуска на мобильной платформе.
POST
/api/v2/content/hash/default

Ответ

  • hex - результирующий хэш в виде шестнадцатеричной строки,

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "hash": "01fa34b589...."
}

Ошибки: E_NOTFOUND, E_SERVER, E_HEAVYPAGE

content

POST/ Возвращает JSON представление кода указанного в параметре template. Если указан дополнительный параметр source равный true или 1, то возвратится JSON представление без выполнения функций и получения данных. Возвращаемое дерево соответствует переданному шаблону и может быть использовано в визуальном конструкторе. Запрос доступен без авторизации.

Запрос

  • template - текст шаблона страницы для разбора,
  • [source] - если равен true или 1, то дерево возвратится без выполнения функций и получения данных.
POST
/api/v2/content

Ответ

  • tree - JSON дерево объектов.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "tree": {"type":"......",
          "children": [
               {...},
               {...}
          ]
    },
}

Ошибки: E_NOTFOUND, E_SERVER

node/{name}

POST/ Вызвает смарт-контракт с указанным именем {name} от имени ноды. Используется для вызова смарт контрактов из OBS контрактов через функцию HTTPRequest. Так как в этом случае мы не можем подписать контракт, то контракт будет подписан приватным ключом ноды. Все остальные параметры, такие же как при отправке контракта. Также нужно учитывать, чтобы вызываемый контракт был привязан к аккаунту. В противном случае, на счету у приватного ключа ноды нет средств на выполнение контракта. Если вызов происходит из obs контракта, то необходимо передать в HTTPRequest токен авторизации $auth_token.

var pars, heads map
heads["Authorization"] = "Bearer " + $auth_token
pars["obs"] = "false"
ret = HTTPRequest("http://localhost:7079/api/v2/node/mycontract", "POST", heads, pars)

Запрос

POST
/api/v2/node/mycontract

Ответ

  • hash - hex хэш отправленной транзакции.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "hash" : "67afbc435634.....",
}

Ошибки: E_CONTRACT, E_EMPTYPUBLIC, E_EMPTYSIGN

maxblockid

GET/ Возвращает максимальный id блока на текущей ноде. Данный метод api не требует авторизации.

Запрос

GET
/api/v2/maxblockid

Ответ

  • max_block_id - максимальный id блока на текущей ноде.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "max_block_id" : 341,
}

Ошибки: E_NOTFOUND

block/{id}

GET/ Возвращает информацию о блоке с указанным ID. Данный метод api не требует авторизации.

Запрос

  • id - id запрашиваемого блока.
POST
/api/v2/block/32

Ответ

  • hash - хэш блока.
  • ecosystem_id - id экосистемы.
  • key_id - каким ключом был подписан блок.
  • time - timestamp генерации блока.
  • tx_count - количество транзакции в блоке.
  • rollbacks_hash - хэш роллбеков, созданных транзакциями блока.

Вариант ответа

200 (OK)
Content-Type: application/json
{
    "hash": "\x1214451d1144a51",
    "ecosystem_id": 1,
    "key_id": -13646477,
    "time": 134415251,
    "tx_count": 3,
    "rollbacks_hash": "\xa1234b1234"
}

Ошибки: E_NOTFOUND

avatar/{ecosystem}/{member}

GET/ Возвращает аватар пользователя (доступно без авторизации)

Запрос

  • ecosystem - id экосистемы пользователя
  • member - id пользователя
GET
/api/v2/avatar/1/7136200061669836581

Ответ

Заголовок Content-Type с типом изображения Изображение в теле

Вариант ответа

200 (OK)
Content-Type: image/png

Ошибки: E_NOTFOUND E_SERVER

config/centrifugo

GET/ Возвращает хост и порт для подключения к centrifugo. Запрос доступен без авторизации.

Запрос

GET
/api/v2/config/centrifugo

Ответ

Строка http://127.0.0.1:8000 в теле ответа

Ошибки: E_SERVER

updnotificator

POST/ инициирует отправку неотправленных сообщений в центрифугу для заданных экосистем и пользователей. Запрос доступен без авторизации.

Запрос

Список вида:

  • id - ID пользователя
  • ecoysystem - ID экосистемы
POST
/updnotificator

Ответ

200 (OK)
Content-Type: application/json
{
    "result": true
}