coopenomics/coopos/net.swagger.yaml

openapi: 3.0.0
info:
  title: API сети COOPOS
  description: Спецификация Net API узла COOPOS (nodeos). Включение плагина — в документации на https://coopenomics.world.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    url: https://coopenomics.world
servers:
  - url: '{protocol}://{host}:{port}/v1/'
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      host:
        default: localhost
      port:
        default: "8080"
components:
  schemas: {}
paths:
  /net/connections:
    post:
      summary: Соединения
      description: Возвращает массив состояний всех пиринговых соединений.
      operationId: connections
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    peer:
                      description: IP-адрес или URL пира
                      type: string
                    connecting:
                      description: true, если идёт установление соединения; иначе false
                      type: boolean
                    syncing:
                      description: true, если пир в процессе синхронизации; иначе false
                      type: boolean
                    last_handshake:
                      description: Структура с подробностями последнего рукопожатия
                      type: object
                      properties:
                        network_version:
                          description: Инкрементальное значение относительно вычисленной базы
                          type: integer
                        chain_id:
                          $ref: 'schemas/Sha256.yaml'
                        node_id:
                          $ref: 'schemas/Sha256.yaml'
                        key:
                          $ref: 'schemas/PublicKey.yaml'
                        time:
                          $ref: 'schemas/DateTimeSeconds.yaml'
                        token:
                          $ref: 'schemas/Sha256.yaml'
                        sig:
                          $ref: 'schemas/Signature.yaml'
                        p2p_address:
                          description: IP-адрес или URL пира
                          type: string
                        last_irreversible_block_num:
                          description: Номер последнего необратимого блока
                          type: integer
                        last_irreversible_block_id:
                          $ref: 'schemas/Sha256.yaml'
                        head_num:
                          description: Номер головы цепи
                          type: integer
                        head_id:
                          $ref: 'schemas/Sha256.yaml'
                        os:
                          description: Название операционной системы
                          type: string
                        agent:
                          description: Имя агента (строка идентификации узла)
                          type: string
                        generation:
                          description: Номер поколения
                          type: integer

  /net/connect:
    post:
      summary: Подключиться
      description: Инициирует соединение с указанным пиром.
      operationId: connect
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - endpoint
              properties:
                endpoint:
                  type: string
                  description: Конечная точка для подключения — IP-адрес или URL

      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                type: string
                description: '«already connected» или «added connection»'

  /net/disconnect:
    post:
      summary: Отключиться
      description: Инициирует разрыв соединения с указанным пиром.
      operationId: disconnect
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - endpoint
              properties:
                endpoint:
                  type: string
                  description: Конечная точка для отключения — IP-адрес или URL

      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                type: string
                description: '«connection removed» или «no known connection for host»'

  /net/status:
    post:
      summary: Статус
      description: Возвращает состояние соединения с указанным пиром.
      operationId: status
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - endpoint
              properties:
                endpoint:
                  type: string
                  description: Конечная точка, для которой запрашивается статус — IP-адрес или URL

      responses:
        '200':
          description: Успешно
          content:
            application/json:
              schema:
                type: object
                properties:
                  peer:
                    description: IP-адрес или URL пира
                    type: string
                  connecting:
                    description: true, если идёт установление соединения; иначе false
                    type: boolean
                  syncing:
                    description: true, если пир в процессе синхронизации; иначе false
                    type: boolean
                  last_handshake:
                    description: Структура с подробностями последнего рукопожатия
                    type: object
                    properties:
                      network_version:
                        description: Инкрементальное значение относительно вычисленной базы
                        type: integer
                      chain_id:
                        $ref: 'schemas/Sha256.yaml'
                      node_id:
                        $ref: 'schemas/Sha256.yaml'
                      key:
                        $ref: 'schemas/PublicKey.yaml'
                      time:
                        $ref: 'schemas/DateTimeSeconds.yaml'
                      token:
                        $ref: 'schemas/Sha256.yaml'
                      sig:
                        $ref: 'schemas/Signature.yaml'
                      p2p_address:
                        description: IP-адрес или URL пира
                        type: string
                      last_irreversible_block_num:
                        description: Номер последнего необратимого блока
                        type: integer
                      last_irreversible_block_id:
                        $ref: 'schemas/Sha256.yaml'
                      head_num:
                        description: Номер головы цепи
                        type: integer
                      head_id:
                        $ref: 'schemas/Sha256.yaml'
                      os:
                        description: Название операционной системы
                        type: string
                      agent:
                        description: Имя агента
                        type: string
                      generation:
                        description: Номер поколения
                        type: integer