openapi: "3.0.0"
info:
  title: Nuts Network API spec
  description: API specification for RPC services available at the nuts-network
  version: 1.0.0
  license:
    name: GPLv3
servers:
  - url: http://localhost:1323
paths:
  /internal/network/v1/transaction:
    parameters:
      - name: start
        description: "Inclusive start of range (in lamport clock); default=0"
        example: 1
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: end
        description: "Exclusive stop of range (in lamport clock); default=∞"
        example: 1000
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
    get:
      summary: "Lists transactions on the DAG"
      description: >
        Lists transactions on the DAG. Since this call returns all transactions on the DAG, care should be taken when there are many of them. A range (start,end) are recommended at all times to avoid overloading the endpoint.

        error returns:
        * 500 - internal server error
      operationId: "listTransactions"
      tags:
        - transactions
      responses:
        "200":
          description: "Successfully listed the transactions"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        default:
          $ref: '../common/error_response.yaml'
  /internal/network/v1/transaction/{ref}:
    parameters:
      - name: ref
        in: path
        description: "Reference of the transaction"
        required: true
        example: "4960afbdf21280ef248081e6e52317735bbb929a204351291b773c252afeebf4"
        schema:
          type: string
    get:
      summary: "Retrieves a transaction"
      description: |
        Retrieves a transaction.

        error returns:
        * 400 - invalid transaction reference
        * 404 - transaction not found
        * 500 - internal server error
      operationId: "getTransaction"
      tags:
        - transactions
      responses:
        "200":
          description: "Transaction is known in the transaction log"
          content:
            application/jose:
              schema:
                type: string
        default:
          $ref: '../common/error_response.yaml'
  /internal/network/v1/transaction/{ref}/payload:
    parameters:
      - name: ref
        in: path
        description: "Reference of the transaction"
        required: true
        example: "4960afbdf21280ef248081e6e52317735bbb929a204351291b773c252afeebf4"
        schema:
          type: string
    get:
      summary: "Gets the transaction payload"
      operationId: "getTransactionPayload"
      description: |
        Gets the transaction payload.

        error returns:
        * 400 - invalid transaction reference
        * 404 - transaction or payload not found
        * 500 - internal server error
      tags:
        - transactions
      responses:
        "200":
          description: "Transaction found (with payload) and returned."
          content:
            application/octet-stream:
              example:
        default:
          $ref: '../common/error_response.yaml'
  /internal/network/v1/diagnostics/peers:
    get:
      summary: "Gets diagnostic information about the node's peers"
      operationId: "getPeerDiagnostics"
      tags:
        - diagnostics
      responses:
        "200":
          description: "Successfully retrieved peers diagnostics"
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/PeerDiagnostics'
        default:
          $ref: '../common/error_response.yaml'
  /internal/network/v1/diagnostics/graph:
    parameters:
      - name: start
        in: query
        description: "Lamport Clock value from where to start rendering (inclusive). If omitted, rendering starts at the root."
        required: false
        example: 2
        schema:
          type: integer
          minimum: 0
      - name: end
        in: query
        description: "Lamport Clock value where to stop rendering (exclusive). If omitted, renders the remainder of the graph. Must be larger than the `start` parameter."
        required: false
        example: 3
        schema:
          type: integer
          minimum: 1
    get:
      summary: "Visualizes the DAG as a graph"
      description: >
        Renders the transactions in the requested range, or the entire graph if no range is specified.
        By default it renders in Graphviz format, which can be rendered to an image using `dot`. 

        error returns:
        * 400 - invalid range
        * 500 - internal server error
      operationId: "renderGraph"
      tags:
        - diagnostics
      responses:
        "200":
          description: "Graph successfully rendered"
          content:
            text/vnd.graphviz:
              schema:
                type: string
        default:
          $ref: '../common/error_response.yaml'
  /internal/network/v1/reprocess:
    post:
      summary: "Reprocess all transactions of the given type, verify and process"
      description: >
        Walks the DAG as subscribers do, only selects TXs of the given type.
        The supported type values correspond with the transaction content-types.
        Transactions are not verified and added to an in-memory queue. For large sets of transactions, memory usage can become high.
        The API returns immediately.
        
        error returns:
        * 400 - missing type
      parameters:
        - name: type
          in: query
          description: the transaction content-type that must be reprocessed
          schema:
            type: string
          example: application/did+json
      operationId: reprocess
      tags:
        - admin
      responses:
        "202":
          description: "The request was accepted, process was started"
  /internal/network/v1/events:
    get:
      summary: "Lists the state of the internal events"
      description: >
        Internal events are used to update network state, retrieve private transactions and update the VDR and VCR.
        New transactions will cause events to be omitted. In normal operation no events should remain.
        The diagnostics page displays the number of failed events. If there are any, this API can be used to get the cause.
        Events are listed by subscriber.
        
        error returns:
        * 500 - internal server error
      operationId: "ListEvents"
      tags:
        - diagnostics
      responses:
        "200":
          description: "Successfully listed the events"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventSubscriber'
        default:
          $ref: '../common/error_response.yaml'
components:
  schemas:
    Event:
      type: object
      description: Non-completed event. An event represents a transaction that is of interest to a specific part of the Nuts node.
      required:
        - hash
        - retries
        - transaction
      properties:
        'type':
          description: "'transaction' or 'payload'"
          type: string
        hash:
          description: Hash is the ID of the Event, usually the same as the transaction reference.
          type: string
        retries:
          description: Number of times the event has been retried.
          type: integer
        latest_notification_attempt:
          description: "Timestamp of the most recent notification attempt. Formatted according to RFC3339. Note: calculation of the next attempt does not use this timestamp."
          type: string
        transaction:
          description: The transaction reference
          type: string
        error:
          description: Lists the last error if the event processing failed due to an error.
          type: string
    EventSubscriber:
      type: object
      description: Non-completed events for a subscriber
      required:
        - name
        - events
      properties:
        name:
          description: Name of the subscriber component
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    PeerDiagnostics:
      type: object
      description: Diagnostic information of a peer.
      properties:
        peers:
          description: IDs of the peer's peers.
          type: array
          items:
            type: string
        uptime:
          description: Number of seconds since the node started.
          type: number
        transactionNum:
          description: Number of transactions on the peer's DAG.
          type: number
        softwareID:
          description: >
            Identification of the particular Nuts implementation of the node.
            For open source implementations it's recommended to specify URL to the public, open source repository.
            Proprietary implementations could specify the product or vendor's name.
          type: string
        softwareVersion:
          description: Indication of the software version of the node. It's recommended to use a (Git) commit ID that uniquely resolves to a code revision, alternatively a semantic version could be used (e.g. 1.2.5).
          type: string
  securitySchemes:
    jwtBearerAuth:
      type: http
      scheme: bearer

security:
  - {}
  - jwtBearerAuth: []
