mirror of
https://github.com/threefoldtech/mycelium.git
synced 2026-04-25 21:12:07 +00:00
242 lines
7.7 KiB
YAML
242 lines
7.7 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/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: Message
|
|
description: Operations on the embedded message subsystem
|
|
|
|
servers:
|
|
- url: 'http://localhost:8989'
|
|
|
|
paths:
|
|
'/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
|
|
|
|
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
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PushMessageBody'
|
|
responses:
|
|
'200':
|
|
description: Message pushed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PushMessageResponse'
|
|
|
|
'/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
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/MessageStatusResponse'
|
|
'404':
|
|
description: Message not found
|
|
|
|
|
|
components:
|
|
schemas:
|
|
InboundMessage:
|
|
description: A message received by the system
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: Id of the message, hex encoded
|
|
type: string
|
|
minLength: 16
|
|
maxLength: 16
|
|
example: 0123456789abcdef
|
|
src_ip:
|
|
description: Sender overlay IP address
|
|
type: string
|
|
format: ipv6
|
|
example: 249:abcd:0123:defa::1
|
|
src_pk:
|
|
description: Sender public key, hex encoded
|
|
type: string
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: fedbca9876543210fedbca9876543210fedbca9876543210fedbca9876543210
|
|
dst_ip:
|
|
description: Receiver overlay IP address
|
|
type: string
|
|
format: ipv6
|
|
example: 34f:b680:ba6e:7ced:355f:346f:d97b:eecb
|
|
dst_pk:
|
|
description: Receiver public key, hex encoded. This is the public key of the system
|
|
type: string
|
|
minLength: 64
|
|
maxLength: 64
|
|
example: 02468ace13579bdf02468ace13579bdf02468ace13579bdf02468ace13579bdf
|
|
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'
|
|
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: 249: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
|
|
|
|
PushMessageResponse:
|
|
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
|
|
minLength: 16
|
|
maxLength: 16
|
|
example: 0123456789abcdef
|
|
|
|
MessageStatusResponse:
|
|
description: Information about an outobund message
|
|
type: object
|
|
properties:
|
|
dst:
|
|
description: Ip address of the receiving node
|
|
type: string
|
|
format: ipv6
|
|
example: 249: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
|
|
msg_len:
|
|
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'
|