docs/_static/network/v1.yaml
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:8081
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'
/internal/network/v1/addressbook:
get:
summary: "Get the address book, listing which nodes will be connected to."
operationId: "getAddressBook"
tags:
- diagnostics
responses:
"200":
description: "Successfully listed the address book"
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Contact'
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
certificate:
description: >
Peer's Certificate
type: string
nodeDID:
description: >
Peer's NodeDID
type: string
address:
description: >
Peer's address. This is an IP if it is an inbound connection.
type: string
Contact:
type: object
description: Describes the contact information of a node.
required:
- address
- attempts
properties:
address:
description: Address of the node.
type: string
did:
description: DID of the node.
type: string
attempts:
description: Number of connection attempts since the node has (re-)started. It is reset to 0 when the connection succeeds.
type: integer
lastAttempt:
description: Timestamp of the last attempt to contact the address.
type: string
format: date-time
nextAttempt:
description: Timestamp of the next attempt to contact the address.
type: string
format: date-time
error:
description: Error message of the last connection attempt.
type: string
securitySchemes:
jwtBearerAuth:
type: http
scheme: bearer
security:
- {}
- jwtBearerAuth: []