991 lines
30 KiB
YAML
991 lines
30 KiB
YAML
openapi: 3.0.2
|
|
info:
|
|
version: "1.0.0"
|
|
|
|
title: Mycelium management
|
|
contact:
|
|
url: "https://github.com/threefoldtech/mycelium"
|
|
license:
|
|
name: Apache 2.0
|
|
url: "https://github.com/threefoldtech/mycelium/blob/master/LICENSE"
|
|
|
|
description: |
|
|
This is the specification of the **mycelium** management API. It is used to perform admin tasks on the system, and
|
|
to perform administrative duties.
|
|
|
|
externalDocs:
|
|
description: For full documentation, check out the mycelium github repo.
|
|
url: "https://github.com/threefoldtech/mycelium"
|
|
|
|
tags:
|
|
- name: Admin
|
|
description: Administrative operations
|
|
- name: Peer
|
|
description: Operations related to peer management
|
|
- name: Route
|
|
description: Operations related to network routes
|
|
- name: Message
|
|
description: Operations on the embedded message subsystem
|
|
- name: Topic
|
|
description: Operations related to message topic configuration
|
|
|
|
servers:
|
|
- url: "http://localhost:8989"
|
|
|
|
paths:
|
|
"/api/v1/admin":
|
|
get:
|
|
tags:
|
|
- Admin
|
|
summary: Get general info about the node
|
|
description: |
|
|
Get general info about the node, which is not related to other more specific functionality
|
|
operationId: getInfo
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Info"
|
|
|
|
"/api/v1/admin/peers":
|
|
get:
|
|
tags:
|
|
- Admin
|
|
- Peer
|
|
summary: List known peers
|
|
description: |
|
|
List all peers known in the system, and info about their connection.
|
|
This includes the endpoint, how we know about the peer, the connection state, and if the connection is alive the amount
|
|
of bytes we've sent to and received from the peer.
|
|
operationId: getPeers
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/PeerStats"
|
|
post:
|
|
tags:
|
|
- Admin
|
|
- Peer
|
|
summary: Add a new peer
|
|
description: |
|
|
Add a new peer identified by the provided endpoint.
|
|
The peer is added to the list of known peers. It will eventually be connected
|
|
to by the standard connection loop of the peer manager. This means that a peer
|
|
which can't be connected to will stay in the system, as it might be reachable
|
|
later on.
|
|
operationId: addPeer
|
|
responses:
|
|
"204":
|
|
description: Peer added
|
|
"400":
|
|
description: Malformed endpoint
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Details about why the endpoint is not valid
|
|
"409":
|
|
description: Peer already exists
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: message saying we already know this peer
|
|
|
|
"/api/v1/admin/peers/{endpoint}":
|
|
delete:
|
|
tags:
|
|
- Admin
|
|
- Peer
|
|
summary: Remove an existing peer
|
|
description: |
|
|
Remove an existing peer identified by the provided endpoint.
|
|
The peer is removed from the list of known peers. If a connection to it
|
|
is currently active, it will be closed.
|
|
operationId: deletePeer
|
|
responses:
|
|
"204":
|
|
description: Peer removed
|
|
"400":
|
|
description: Malformed endpoint
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Details about why the endpoint is not valid
|
|
"404":
|
|
description: Peer doesn't exist
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: message saying we don't know this peer
|
|
|
|
"/api/v1/admin/routes/selected":
|
|
get:
|
|
tags:
|
|
- Admin
|
|
- Route
|
|
summary: List all selected routes
|
|
description: |
|
|
List all selected routes in the system, and their next hop identifier, metric and sequence number.
|
|
It is possible for a route to be selected and have an infinite metric. This route will however not forward packets.
|
|
operationId: getSelectedRoutes
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Route"
|
|
|
|
"/api/v1/admin/routes/fallback":
|
|
get:
|
|
tags:
|
|
- Admin
|
|
- Route
|
|
summary: List all active fallback routes
|
|
description: |
|
|
List all fallback routes in the system, and their next hop identifier, metric and sequence number.
|
|
These routes are available to be selected in case the selected route for a destination suddenly fails, or gets retracted.
|
|
operationId: getFallbackRoutes
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Route"
|
|
|
|
"/api/v1/admin/routes/queried":
|
|
get:
|
|
tags:
|
|
- Admin
|
|
- Route
|
|
summary: List all currently queried subnets
|
|
description: |
|
|
List all currently queried subnets in the system, and the amount of seconds until the query expires.
|
|
These subnets are actively being probed in the network. If no route to them is discovered before the query expires,
|
|
they will be marked as not reachable temporarily.
|
|
operationId: getQueriedSubnets
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/QueriedSubnet"
|
|
|
|
"/api/v1/admin/routes/no_route":
|
|
get:
|
|
tags:
|
|
- Admin
|
|
- Route
|
|
summary: List all subnets which are explicitly marked as no route
|
|
description: |
|
|
List all subnets in the system which are marked no route, and the amount of seconds until the query expires.
|
|
These subnets have recently been probed in the network, and no route for them was discovered in time. No more
|
|
route requests will be send for these subnets until the entry expires.
|
|
operationId: getNoRouteEntries
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/NoRouteSubnet"
|
|
|
|
"/api/v1/messages":
|
|
get:
|
|
tags:
|
|
- Message
|
|
summary: Get a message from the inbound message queue
|
|
description: |
|
|
Get a message from the inbound message queue. By default, the message is removed from the queue and won't be shown again.
|
|
If the peek query parameter is set to true, the message will be peeked, and the next call to this endpoint will show the same message.
|
|
This method returns immediately by default: a message is returned if one is ready, and if there isn't nothing is returned. If the timeout
|
|
query parameter is set, this call won't return for the given amount of seconds, unless a message is received
|
|
operationId: popMessage
|
|
parameters:
|
|
- in: query
|
|
name: peek
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
description: Whether to peek the message or not. If this is true, the message won't be removed from the inbound queue when it is read
|
|
example: true
|
|
- in: query
|
|
name: timeout
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
description: |
|
|
Amount of seconds to wait for a message to arrive if one is not available. Setting this to 0 is valid and will return
|
|
a message if present, or return immediately if there isn't
|
|
example: 60
|
|
- in: query
|
|
name: topic
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
minLength: 0
|
|
maxLength: 340
|
|
description: |
|
|
Optional filter for loading messages. If set, the system checks if the message has the given string at the start. This way
|
|
a topic can be encoded.
|
|
example: example.topic
|
|
responses:
|
|
"200":
|
|
description: Message retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InboundMessage"
|
|
"204":
|
|
description: No message ready
|
|
post:
|
|
tags:
|
|
- Message
|
|
summary: Submit a new message to the system.
|
|
description: |
|
|
Push a new message to the systems outbound message queue. The system will continuously attempt to send the message until
|
|
it is either fully transmitted, or the send deadline is expired.
|
|
operationId: pushMessage
|
|
parameters:
|
|
- in: query
|
|
name: reply_timeout
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
description: |
|
|
Amount of seconds to wait for a reply to this message to come in. If not set, the system won't wait for a reply and return
|
|
the ID of the message, which can be used later. If set, the system will wait for at most the given amount of seconds for a reply
|
|
to come in. If a reply arrives, it is returned to the client. If not, the message ID is returned for later use.
|
|
example: 120
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PushMessageBody"
|
|
responses:
|
|
"200":
|
|
description: We received a reply within the specified timeout
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InboundMessage"
|
|
|
|
"201":
|
|
description: Message pushed successfully, and not waiting for a reply
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PushMessageResponseId"
|
|
"408":
|
|
description: The system timed out waiting for a reply to the message
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PushMessageResponseId"
|
|
|
|
"/api/v1/messages/reply/{id}":
|
|
post:
|
|
tags:
|
|
- Message
|
|
summary: Reply to a message with the given ID
|
|
description: |
|
|
Submits a reply message to the system, where ID is an id of a previously received message. If the sender is waiting
|
|
for a reply, it will bypass the queue of open messages.
|
|
operationId: pushMessageReply
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: hex
|
|
minLength: 16
|
|
maxLength: 16
|
|
example: abcdef0123456789
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PushMessageBody"
|
|
responses:
|
|
"204":
|
|
description: successfully submitted the reply
|
|
|
|
"/api/v1/messages/status/{id}":
|
|
get:
|
|
tags:
|
|
- Message
|
|
summary: Get the status of an outbound message
|
|
description: |
|
|
Get information about the current state of an outbound message. This can be used to check the transmission
|
|
state, size and destination of the message.
|
|
operationId: getMessageInfo
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: hex
|
|
minLength: 16
|
|
maxLength: 16
|
|
example: abcdef0123456789
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MessageStatusResponse"
|
|
"404":
|
|
description: Message not found
|
|
|
|
"/api/v1/messages/topics/default":
|
|
get:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Get the default topic action
|
|
description: |
|
|
Get the default action for topics that are not explicitly configured (accept or reject).
|
|
operationId: getDefaultTopicAction
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DefaultTopicActionResponse"
|
|
put:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Set the default topic action
|
|
description: |
|
|
Set the default action for topics that are not explicitly configured (accept or reject).
|
|
operationId: setDefaultTopicAction
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DefaultTopicActionRequest"
|
|
responses:
|
|
"204":
|
|
description: Default topic action set successfully
|
|
|
|
"/api/v1/messages/topics":
|
|
get:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Get all configured topics
|
|
description: |
|
|
Get all topics that are explicitly configured in the system.
|
|
operationId: getTopics
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: byte
|
|
description: Base64 encoded topic identifier
|
|
post:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Add a new topic
|
|
description: |
|
|
Add a new topic to the system's whitelist.
|
|
operationId: addTopic
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to add
|
|
responses:
|
|
"201":
|
|
description: Topic added successfully
|
|
|
|
"/api/v1/messages/topics/{topic}":
|
|
delete:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Remove a topic
|
|
description: |
|
|
Remove a topic from the system's whitelist.
|
|
operationId: removeTopic
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to remove (base64 encoded)
|
|
responses:
|
|
"204":
|
|
description: Topic removed successfully
|
|
"400":
|
|
description: Invalid topic format
|
|
|
|
"/api/v1/messages/topics/{topic}/sources":
|
|
get:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Get sources for a topic
|
|
description: |
|
|
Get all sources (subnets) that are allowed to send messages for a specific topic.
|
|
operationId: getTopicSources
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to get sources for (base64 encoded)
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Subnet in CIDR notation
|
|
"400":
|
|
description: Invalid topic format
|
|
post:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Add a source to a topic
|
|
description: |
|
|
Add a source (subnet) that is allowed to send messages for a specific topic.
|
|
operationId: addTopicSource
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to add a source to (base64 encoded)
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TopicSourceRequest"
|
|
responses:
|
|
"204":
|
|
description: Source added successfully
|
|
"400":
|
|
description: Invalid topic format or subnet
|
|
|
|
"/api/v1/messages/topics/{topic}/sources/{subnet}":
|
|
delete:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Remove a source from a topic
|
|
description: |
|
|
Remove a source (subnet) that is allowed to send messages for a specific topic.
|
|
operationId: removeTopicSource
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to remove a source from (base64 encoded)
|
|
- in: path
|
|
name: subnet
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The subnet to remove as a source
|
|
responses:
|
|
"204":
|
|
description: Source removed successfully
|
|
"400":
|
|
description: Invalid topic format or subnet
|
|
|
|
"/api/v1/messages/topics/{topic}/forward":
|
|
get:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Get the forward socket for a topic
|
|
description: |
|
|
Get the socket path where messages for a specific topic are forwarded to.
|
|
operationId: getTopicForwardSocket
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to get the forward socket for (base64 encoded)
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
nullable: true
|
|
description: The socket path where messages are forwarded to
|
|
"400":
|
|
description: Invalid topic format
|
|
put:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Set the forward socket for a topic
|
|
description: |
|
|
Set the socket path where messages for a specific topic should be forwarded to.
|
|
operationId: setTopicForwardSocket
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to set the forward socket for (base64 encoded)
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TopicForwardSocketRequest"
|
|
responses:
|
|
"204":
|
|
description: Forward socket set successfully
|
|
"400":
|
|
description: Invalid topic format
|
|
delete:
|
|
tags:
|
|
- Message
|
|
- Topic
|
|
summary: Remove the forward socket for a topic
|
|
description: |
|
|
Remove the socket path where messages for a specific topic are forwarded to.
|
|
operationId: removeTopicForwardSocket
|
|
parameters:
|
|
- in: path
|
|
name: topic
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: byte
|
|
description: The topic to remove the forward socket for (base64 encoded)
|
|
responses:
|
|
"204":
|
|
description: Forward socket removed successfully
|
|
"400":
|
|
description: Invalid topic format
|
|
"/api/v1/pubkey/{mycelium_ip}":
|
|
get:
|
|
summary: Get the pubkey from node ip
|
|
description: |
|
|
Get the node's public key from it's IP address.
|
|
operationId: getPublicKeyFromIp
|
|
parameters:
|
|
- in: path
|
|
name: mycelium_ip
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: ipv6
|
|
example: 5fd:7636:b80:9ad0::1
|
|
responses:
|
|
"200":
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PublicKeyResponse"
|
|
"404":
|
|
description: Public key not found
|
|
|
|
components:
|
|
schemas:
|
|
Info:
|
|
description: General information about a node
|
|
type: object
|
|
properties:
|
|
nodeSubnet:
|
|
description: The subnet owned by the node and advertised to peers
|
|
type: string
|
|
example: 54f:b680:ba6e:7ced::/64
|
|
nodePubkey:
|
|
description: The public key of the node
|
|
type: string
|
|
format: hex
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: 02468ace13579bdf02468ace13579bdf02468ace13579bdf02468ace13579bdf
|
|
|
|
Endpoint:
|
|
description: Identification to connect to a peer
|
|
type: object
|
|
properties:
|
|
proto:
|
|
description: Protocol used
|
|
type: string
|
|
enum:
|
|
- "tcp"
|
|
- "quic"
|
|
example: tcp
|
|
socketAddr:
|
|
description: The socket address used
|
|
type: string
|
|
example: 192.0.2.6:9651
|
|
|
|
PeerStats:
|
|
description: Info about a peer
|
|
type: object
|
|
properties:
|
|
endpoint:
|
|
$ref: "#/components/schemas/Endpoint"
|
|
type:
|
|
description: How we know about this peer
|
|
type: string
|
|
enum:
|
|
- "static"
|
|
- "inbound"
|
|
- "linkLocalDiscovery"
|
|
example: static
|
|
connectionState:
|
|
description: The current state of the connection to the peer
|
|
type: string
|
|
enum:
|
|
- "alive"
|
|
- "connecting"
|
|
- "dead"
|
|
example: alive
|
|
txBytes:
|
|
description: The amount of bytes transmitted to this peer
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
example: 464531564
|
|
rxBytes:
|
|
description: The amount of bytes received from this peer
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
example: 64645089
|
|
|
|
Route:
|
|
description: Information about a route
|
|
type: object
|
|
properties:
|
|
subnet:
|
|
description: The overlay subnet for which this is the route
|
|
type: string
|
|
example: 469:1348:ab0c:a1d8::/64
|
|
nextHop:
|
|
description: A way to identify the next hop of the route, where forwarded packets will be sent
|
|
type: string
|
|
example: TCP 203.0.113.2:60128 <-> 198.51.100.27:9651
|
|
metric:
|
|
description: The metric of the route, an estimation of how long the packet will take to arrive at its final destination
|
|
oneOf:
|
|
- description: A finite metric value
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
maximum: 65534
|
|
example: 13
|
|
- description: An infinite (unreachable) metric. This is always `infinite`
|
|
type: string
|
|
example: infinite
|
|
seqno:
|
|
description: the sequence number advertised with this route by the source
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
maximum: 65535
|
|
example: 1
|
|
|
|
QueriedSubnet:
|
|
description: Information about a subnet currently being queried
|
|
type: object
|
|
properties:
|
|
subnet:
|
|
description: The overlay subnet which we are currently querying
|
|
type: string
|
|
example: 503:5478:df06:d79a::/64
|
|
expiration:
|
|
description: The amount of seconds until the query expires
|
|
type: string
|
|
example: "37"
|
|
|
|
NoRouteSubnet:
|
|
description: Information about a subnet which is marked as no route
|
|
type: object
|
|
properties:
|
|
subnet:
|
|
description: The overlay subnet which is marked
|
|
type: string
|
|
example: 503:5478:df06:d79a::/64
|
|
expiration:
|
|
description: The amount of seconds until the entry expires
|
|
type: string
|
|
example: "37"
|
|
|
|
InboundMessage:
|
|
description: A message received by the system
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: Id of the message, hex encoded
|
|
type: string
|
|
format: hex
|
|
minLength: 16
|
|
maxLength: 16
|
|
example: 0123456789abcdef
|
|
srcIp:
|
|
description: Sender overlay IP address
|
|
type: string
|
|
format: ipv6
|
|
example: 449:abcd:0123:defa::1
|
|
srcPk:
|
|
description: Sender public key, hex encoded
|
|
type: string
|
|
format: hex
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: fedbca9876543210fedbca9876543210fedbca9876543210fedbca9876543210
|
|
dstIp:
|
|
description: Receiver overlay IP address
|
|
type: string
|
|
format: ipv6
|
|
example: 34f:b680:ba6e:7ced:355f:346f:d97b:eecb
|
|
dstPk:
|
|
description: Receiver public key, hex encoded. This is the public key of the system
|
|
type: string
|
|
format: hex
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: 02468ace13579bdf02468ace13579bdf02468ace13579bdf02468ace13579bdf
|
|
topic:
|
|
description: An optional message topic
|
|
type: string
|
|
format: byte
|
|
minLength: 0
|
|
maxLength: 340
|
|
example: hpV+
|
|
payload:
|
|
description: The message payload, encoded in standard alphabet base64
|
|
type: string
|
|
format: byte
|
|
example: xuV+
|
|
|
|
PushMessageBody:
|
|
description: A message to send to a given receiver
|
|
type: object
|
|
properties:
|
|
dst:
|
|
$ref: "#/components/schemas/MessageDestination"
|
|
topic:
|
|
description: An optional message topic
|
|
type: string
|
|
format: byte
|
|
minLength: 0
|
|
maxLength: 340
|
|
example: hpV+
|
|
payload:
|
|
description: The message to send, base64 encoded
|
|
type: string
|
|
format: byte
|
|
example: xuV+
|
|
|
|
MessageDestination:
|
|
oneOf:
|
|
- description: An IP in the subnet of the receiver node
|
|
type: object
|
|
properties:
|
|
ip:
|
|
description: The target IP of the message
|
|
format: ipv6
|
|
example: 449:abcd:0123:defa::1
|
|
- description: The hex encoded public key of the receiver node
|
|
type: object
|
|
properties:
|
|
pk:
|
|
description: The hex encoded public key of the target node
|
|
type: string
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: bb39b4a3a4efd70f3e05e37887677e02efbda14681d0acd3882bc0f754792c32
|
|
|
|
PushMessageResponseId:
|
|
description: The ID generated for a message after pushing it to the system
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: Id of the message, hex encoded
|
|
type: string
|
|
format: hex
|
|
minLength: 16
|
|
maxLength: 16
|
|
example: 0123456789abcdef
|
|
|
|
MessageStatusResponse:
|
|
description: Information about an outbound message
|
|
type: object
|
|
properties:
|
|
dst:
|
|
description: IP address of the receiving node
|
|
type: string
|
|
format: ipv6
|
|
example: 449:abcd:0123:defa::1
|
|
state:
|
|
$ref: "#/components/schemas/TransmissionState"
|
|
created:
|
|
description: Unix timestamp of when this message was created
|
|
type: integer
|
|
format: int64
|
|
example: 1649512789
|
|
deadline:
|
|
description: Unix timestamp of when this message will expire. If the message is not received before this, the system will give up
|
|
type: integer
|
|
format: int64
|
|
example: 1649513089
|
|
msgLen:
|
|
description: Length of the message in bytes
|
|
type: integer
|
|
minimum: 0
|
|
example: 27
|
|
|
|
TransmissionState:
|
|
description: The state of an outbound message in it's lifetime
|
|
oneOf:
|
|
- type: string
|
|
enum: ["pending", "received", "read", "aborted"]
|
|
example: "received"
|
|
- type: object
|
|
properties:
|
|
sending:
|
|
type: object
|
|
properties:
|
|
pending:
|
|
type: integer
|
|
minimum: 0
|
|
example: 5
|
|
sent:
|
|
type: integer
|
|
minimum: 0
|
|
example: 17
|
|
acked:
|
|
type: integer
|
|
minimum: 0
|
|
example: 3
|
|
example: "received"
|
|
|
|
PublicKeyResponse:
|
|
description: Public key requested based on a node's IP
|
|
type: object
|
|
properties:
|
|
NodePubKey:
|
|
type: string
|
|
format: hex
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: 02468ace13579bdf02468ace13579bdf02468ace13579bdf02468ace13579bdf
|
|
|
|
DefaultTopicActionResponse:
|
|
description: Response for the default topic action
|
|
type: object
|
|
properties:
|
|
accept:
|
|
description: Whether unconfigured topics are accepted by default
|
|
type: boolean
|
|
example: true
|
|
|
|
DefaultTopicActionRequest:
|
|
description: Request to set the default topic action
|
|
type: object
|
|
properties:
|
|
accept:
|
|
description: Whether to accept unconfigured topics by default
|
|
type: boolean
|
|
example: true
|
|
|
|
TopicInfo:
|
|
description: Information about a configured topic
|
|
type: object
|
|
properties:
|
|
topic:
|
|
description: The topic identifier (base64 encoded)
|
|
type: string
|
|
format: byte
|
|
example: "ZXhhbXBsZS50b3BpYw=="
|
|
sources:
|
|
description: List of subnets that are allowed to send messages for this topic
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: "503:5478:df06:d79a::/64"
|
|
forward_socket:
|
|
description: Optional socket path where messages for this topic are forwarded to
|
|
type: string
|
|
nullable: true
|
|
example: "/var/run/mycelium/topic_socket"
|
|
|
|
TopicSourceRequest:
|
|
description: Request to add a source to a topic whitelist
|
|
type: object
|
|
properties:
|
|
subnet:
|
|
description: The subnet to add as a source in CIDR notation
|
|
type: string
|
|
example: "503:5478:df06:d79a::/64"
|
|
|
|
TopicForwardSocketRequest:
|
|
description: Request to set a forward socket for a topic
|
|
type: object
|
|
properties:
|
|
socket_path:
|
|
description: The socket path where messages should be forwarded to
|
|
type: string
|
|
example: "/var/run/mycelium/topic_socket"
|