openapi: 3.0.3
info:
    title: Symbol Statistic Service API Documentation
    version: '1.1.4'
servers:
    - url: 'https://testnet.symbol.services'
      description: Testnet server
    - url: 'https://symbol.services'
      description: Mainnet server
    - url: 'http://127.0.0.1:4001'
      description: Local server
paths:
    /nodes:
        get:
            summary: Returns the list of known nodes that are compatible with the current catapult version.
            tags:
                - node
            operationId: getNodes
            parameters:
                - name: filter
                  in: query
                  required: false
                  description: Filter the nodes by the optional filter.
                  example: suggested
                  schema:
                      $ref: '#/components/schemas/NodeListFilter'
                - name: limit
                  in: query
                  required: false
                  description: The maximum number of nodes to be returned.
                  example: 100
                  schema:
                      $ref: '#/components/schemas/NodeListLimit'
                - name: ssl
                  in: query
                  required: false
                  description: Filter nodes according to HTTPS support.
                  example: true
                  schema:
                      $ref: '#/components/schemas/NodeListSSL'
                - name: order
                  in: query
                  required: false
                  description: Sorts and samples the nodes to be returned
                  example: random
                  schema:
                      $ref: '#/components/schemas/NodeListOrder'
            responses:
                200:
                    description: The list of known nodes.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/NodeInfo'
    /nodes/{publicKey}:
        get:
            summary: Returns information about the node with the given main account.
            tags:
                - node
            operationId: getNode
            parameters:
                - name: publicKey
                  required: true
                  description: The node's main account's public key.
                  in: path
                  schema:
                      type: string
                      pattern: '^([0-9A-Fa-f]){64}$'
                  example: E3FC28889BDE31406465167F1D9D6A16DCA1FF67A3BABFA5E5A8596478848F78
            responses:
                200:
                    description: The node information.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeInfo'
                404:
                    description: There is no node with the given main account.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
    /nodes/nodePublicKey/{nodePublicKey}:
        get:
            summary: Returns the node information for the given transport public key.
            tags:
                - node
            operationId: getNodeByNodePublicKey
            parameters:
                - name: nodePublicKey
                  required: true
                  description: The node's transport public key.
                  in: path
                  schema:
                      type: string
                      pattern: '^([0-9A-Fa-f]){64}$'
                  example: E3FC28889BDE31406465167F1D9D6A16DCA1FF67A3BABFA5E5A8596478848F78
            responses:
                200:
                    description: The node information for the given transport public key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeInfo'
                404:
                    description: There is no node with the given transport public key.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
    /nodesHostDetail:
        get:
            summary: Returns the list of hosting details for all the known nodes.
            tags:
                - node
            operationId: getNodesHostDetail
            responses:
                200:
                    description: The list of the hosting details.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/HostDetail'
    /nodesStats:
        get:
            summary: Returns the summary of the number of nodes per role type.
            tags:
                - node
            operationId: getNodeStats
            responses:
                200:
                    description: The summary of the number of nodes per role type.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeStats'
    /nodesHeightStats:
        get:
            summary: Returns the summary of the number of nodes per height and finalized height.
            tags:
                - node
            operationId: getNodeHeightStats
            responses:
                200:
                    description: The summary of the number of nodes per height and finalized height.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeHeightStats'
    /timeSeries/nodeCount:
        get:
            summary: Returns the summary of the number of nodes per role over time.
            tags:
                - node
            operationId: getNodeCount
            responses:
                200:
                    description: The summary of the number of nodes per role over time.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/TimeSeriesNodeCount'

components:
    schemas:
        Error:
            description: An error has occurred processing the request.
            type: object
            required:
                - message
                - code
            properties:
                code:
                    type: string
                    example: ResourceNotFound
                message:
                    type: string
                    example: no resource exists
        TimeSeriesNodeCount:
            type: object
            description: Summary of the number of nodes per role over time.
            allOf:
                - $ref: '#/components/schemas/NodeStatsNodeTypes'
                - type: object
                  properties:
                      total:
                          description: Total number of nodes
                          type: integer
                          example: 64
        NetworkType:
            type: integer
            enum:
                - 104
                - 152
            description: |
                Network type:
                * 0x68 (104 decimal) - Public main network.
                * 0x98 (152 decimal) - Public test network.
            example: 144
        NodeHeightStatValue:
            type: object
            description: A single value of the Node Height Stats.
            properties:
                value:
                    description: Height, as a string because it represents a 64-bit integer.
                    type: string
                    example: '28080'
                count:
                    description: Number of nodes currently at that height.
                    type: integer
                    format: int32
                    example: 10
        NodeHeightStats:
            type: object
            description: The summary of the number of nodes per height and finalized height.
            required:
                - height
                - finalizedHeight
                - date
            properties:
                height:
                    description: Histogram of chain heights.
                    type: array
                    items:
                        $ref: '#/components/schemas/NodeHeightStatValue'
                finalizedHeight:
                    description: Histogram of chain [finalization](https://docs.symbolplatform.com/concepts/block.html#finalization) heights.
                    type: array
                    items:
                        $ref: '#/components/schemas/NodeHeightStatValue'
                date:
                    type: string
                    description: Date and time when the data was collected.
                    example: '2021-10-30T01:12:35.746Z'
        NodeStatsNodeTypes:
            type: object
            additionalProperties: true
            # Note, we could have a large number of possible role types once IPv6 and IPv4 are introduced
            description: The number of nodes indexed by role type.
        NodeStatsNodeVersion:
            type: object
            additionalProperties: true
            description: The number of nodes indexed by version.
        NodeStats:
            description: The summary of the number of nodes per role type.
            type: object
            required:
                - nodeTypes
                - nodeVersion
            properties:
                nodeTypes:
                    $ref: '#/components/schemas/NodeStatsNodeTypes'
                nodeVersion:
                    $ref: '#/components/schemas/NodeStatsNodeVersion'
        NodeListLimit:
            type: integer
            example: 30
        NodeListFilter:
            type: string
            description: |
                `suggested`: All available API nodes that have a REST endpoint and are online.
                `preferred`: Preferred API nodes that have a REST endpoint and are online. Preferred nodes match some specific domains.
            enum:
                - 'suggested'
                - 'preferred'
            example: 'preferred'
        NodeListOrder:
            type: string
            description: |
                'natural': Nodes are returned in the order they are stored in the database.
                `random`: Default list order when a limit is specified. Returns {limit} number of random nodes, ordering falls back to 'natural' when limit is not specified.
            enum:
                - 'natural'
                - 'random'
            example: 'random'
        NodeListSSL:
            description: When true, return only nodes which support HTTPS.
            type: boolean
            example: true
        PeerStatus:
            type: object
            description: The status of the peer node.
            required:
                - isAvailable
                - lastStatusCheck
            properties:
                lastStatusCheck:
                    description: When was the peer last contacted, in milliseconds elapsed since UNIX epoch (January 1, 1970 00:00:00 UTC).
                    type: integer
                    format: int64
                    example: 1635515531373
                isAvailable:
                    description: Whether the node is currently available (reachable and answering queries).
                    type: boolean
                    example: true
        NodeStatus:
            type: object
            description: The status of the REST gateway.
            properties:
                apiNode:
                    description: Whether the front-end REST gateway is up and running. Possible values are `up` and `down`. Node needs to be restarted if `down`.
                    type: string
                    example: up
                db:
                    description: Whether the back-end database is up and running. Possible values are `up` and `down`. Node needs to be restarted if `down`.
                    type: string
                    example: down
        Finalization:
            description: Status of the [finalization](https://docs.symbolplatform.com/concepts/block.html#finalization) gadget.
            type: object
            properties:
                height:
                    type: integer
                    format: int32
                    description: |
                        The latest finalized block of the blockchain.
                        This block and all blocks before it are immutable and cannot be rolled back.
                    example: 512112
                epoch:
                    description: Current [finalization epoch](https://docs.symbolplatform.com/concepts/block.html#finalization).
                    type: integer
                    format: int32
                    example: 713
                point:
                    description: Current [finalization point](https://docs.symbolplatform.com/concepts/block.html#finalization).
                    type: integer
                    format: int32
                    example: 13
                hash:
                    type: string
                    example: 7C9BDF478CB18562A078F191867CB9B3FB12601AE0C69606A34C602A0F7D47EB
        WebSocketStatus:
            type: object
            properties:
                isAvailable:
                    type: boolean
                    example: true
                wss:
                    type: boolean
                    example: true
                url:
                    type: string
                    example: wss://symbol.node.dev:3001/ws
        ApiStatus:
            type: object
            description: The status of the API node. Information comes from the REST gateway.
            required:
                - webSocket
                - restGatewayUrl
                - isAvailable
                - lastStatusCheck
                - nodePublicKey
                - isHttpsEnabled
                - chainHeight
                - finalization
                - restVersion
            properties:
                webSocket:
                    $ref: '#/components/schemas/WebSocketStatus'
                restGatewayUrl:
                    type: string
                    description: The REST gateway URL ready to be connected to.
                    example: 'https://symbol.node.dev:3001'
                isAvailable:
                    type: boolean
                    description: Whether the API is ready to accept queries.
                    example: true
                lastStatusCheck:
                    description: When was the API last checked, in milliseconds elapsed since UNIX epoch (January 1, 1970 00:00:00 UTC).
                    type: integer
                    format: int64
                    example: 1635531195763
                nodeStatus:
                    $ref: '#/components/schemas/NodeStatus'
                isHttpsEnabled:
                    type: boolean
                    description: Whether the API accepts connections through HTTPS.
                    example: true
                nodePublicKey:
                    type: string
                    description: |
                        Node's public key used to stablish TLS connections and
                        [delegated harvesting](https://docs.symbolplatform.com/guides/harvesting/activating-delegated-harvesting-manual.html), for example.
                    example: A2160AB911943082C88109DD8B65A0082EF547CA7C28F001F857112F7ADD9B3D
                chainHeight:
                    type: integer
                    description: Current chain height as reported by this node.
                    format: int32
                    example: 512127
                finalization:
                    $ref: '#/components/schemas/Finalization'
                restVersion:
                    type: string
                    description: Version of the REST API used by this node.
                    example: 2.3.7
        Coordinates:
            type: object
            description: The world coordinates of the node based on its IP address.
            required:
                - latitude
                - longitude
            properties:
                latitude:
                    type: integer
                    example: 54.7091
                longitude:
                    type: integer
                    example: 25.2971
        HostDetail:
            type: object
            description: Location details of the node.
            required:
                - host
            properties:
                host:
                    type: string
                    description: The IP or hostname of the node.
                    example: somehost.symbol.io
                coordinates:
                    $ref: '#/components/schemas/Coordinates'
                location:
                    type: string
                    description: Text description of the host's location.
                    example: 'Ashburn, VA, United States'
                ip:
                    type: string
                    example: '3.86.20.100'
                organization:
                    type: string
                    description: Text description of the organization managing this node.
                    example: 'My VPC provider'
                as:
                    description: AS number and organization, separated by space (RIR).
                    type: string
                    example: 'Some Company, Inc.'
                continent:
                    type: string
                    example: 'North America'
                country:
                    type: string
                    example: 'United States'
                region:
                    type: string
                    example: 'VA'
                city:
                    type: string
                    example: 'Ashburn'
                district:
                    type: string
                    example: 'Springfield'
                zip:
                    type: string
                    example: '20149'
        NodeInfo:
            type: object
            description: Node information gathered from the chain by the statistics service.
            required:
                - publicKey
                - roles
                - version
                - friendlyName
                - networkGenerationHashSeed
                - port
                - host
                - peerStatus
                - hostDetail
            properties:
                publicKey:
                    type: string
                    description: Node's main account's public key.
                    example: E3FC28889BDE31406465167F1D9D6A16DCA1FF67A3BABFA5E5A8596478848FCC
                roles:
                    type: integer
                    description: |
                        A number that defines the different roles the node provides. Possible roles are:
                        * 1 - Peer node.
                        * 2 - API node.
                        * 4 - Voting node.
                        * 64 - IPv4 compatible node
                        * 128 - IPv6 compatible node.

                        The values are bitwise added together, for example:
                        1 = Only Peer.
                        2 = Only API.
                        3 = Both Peer and API node.
                        7 = Peer, API and Voting node.
                        65 = IPv4 and Peer node.
                    example: 3
                version:
                    type: integer
                    description: |
                        The version is encoded as a single 4-byte integer, where the Most-Significant Byte
                        encodes the Major version, and the rest of bytes are the Minor, the Micro and the Patch version.
                        For example, version 16777472 (decimal) is 01000100h (hex), which corresponds to version 1.0.1.0.
                    example: 16777728
                friendlyName:
                    type: string
                    description: Node friendly name.
                    example: My Node
                networkGenerationHashSeed:
                    type: string
                    description: |
                        Hash seed of the network this node is connected to.
                        All nodes connected to the same network have the same
                        [Hash Seed](https://docs.symbolplatform.com/guides/network/configuring-network-properties.html#network-configuration).
                    example: 3B5E1FA6445653C971A50687E75E6D09FB30481055E3990C84B25E9222DC1155
                port:
                    type: integer
                    description: Port used for the communication.
                    example: 7900
                networkIdentifier:
                    $ref: '#/components/schemas/NetworkType'
                host:
                    type: string
                    description: Server IP or Hostname
                    example: somehost.symbol.io
                peerStatus:
                    $ref: '#/components/schemas/PeerStatus'
                apiStatus:
                    $ref: '#/components/schemas/ApiStatus'
                hostDetail:
                    $ref: '#/components/schemas/HostDetail'