Skip to content

M
mybee
Commit a1175610 authored by Janoš Guljaš's avatar Janoš Guljaš Committed by GitHub
Browse files
Options

update openapi specifications (#624) 

Co-authored-by: default avatarMetacertain <metacertain@gmail.com>
parent 082629c3
Hide whitespace changes
Inline Side-by-side
Showing with 343 additions and 98 deletions
openapi/Swarm.yaml
View file @ a1175610
...@@ -30,13 +30,32 @@ servers: ...@@ -30,13 +30,32 @@ servers:
port: port:
default: 8080 default: 8080
description: Service port provided in bee node config description: Service port provided in bee node config
paths: paths:
'/bytes': '/bytes':
post: post:
summary: 'Upload data' summary: 'Upload data'
tags: tags:
- 'Endpoints on local bee node' - Bytes
parameters:
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
type: boolean
required: false
description: Represents the pinning state of the bytes
- in: header
name: swarm-encrypt
schema:
type: boolean
required: false
description: Represents the encrypting state of the bytes
requestBody: requestBody:
content: content:
application/octet-stream: application/octet-stream:
...@@ -58,8 +77,8 @@ paths: ...@@ -58,8 +77,8 @@ paths:
'/bytes/{reference}': '/bytes/{reference}':
get: get:
summary: 'Get referenced data' summary: 'Get referenced data'
tags: tags:
- 'Endpoints on local bee node' - Bytes
parameters: parameters:
- in: path - in: path
name: reference name: reference
...@@ -83,26 +102,26 @@ paths: ...@@ -83,26 +102,26 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
'/chunks/{reference}': '/chunks/{reference}':
get: get:
summary: 'Get Chunk' summary: 'Get Chunk'
tags: tags:
- 'Endpoints on local bee node' - Chunk
parameters: parameters:
- in: path - in: path
name: reference name: reference
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference' $ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference'
required: true required: true
description: Swarm address of chunk description: Swarm address of chunk
responses: responses:
'200': '200':
description: Retrieved chunk content description: Retrieved chunk content
content: content:
application/octet-stream: application/octet-stream:
schema: schema:
type: string type: string
format: binary format: binary
'400': '400':
$ref: 'SwarmCommon.yaml#/components/responses/400' $ref: 'SwarmCommon.yaml#/components/responses/400'
...@@ -114,15 +133,15 @@ paths: ...@@ -114,15 +133,15 @@ paths:
description: Default response description: Default response
post: post:
summary: 'Upload Chunk' summary: 'Upload Chunk'
tags: tags:
- 'Endpoints on local bee node' - Chunk
parameters: parameters:
- in: header - in: header
name: swarm-tag-uid name: swarm-tag-uid
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid' $ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false required: false
description: Uid of chunk description: Associate upload with an existing Tag UID
- in: header - in: header
name: swarm-pin name: swarm-pin
schema: schema:
...@@ -134,7 +153,7 @@ paths: ...@@ -134,7 +153,7 @@ paths:
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference' $ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference'
required: true required: true
description: Swarm address of chunk description: Swarm address of chunk
requestBody: requestBody:
content: content:
application/octet-stream: application/octet-stream:
...@@ -158,8 +177,8 @@ paths: ...@@ -158,8 +177,8 @@ paths:
'/files': '/files':
post: post:
summary: 'Upload file' summary: 'Upload file'
tags: tags:
- 'Endpoints on local bee node' - File
parameters: parameters:
- in: query - in: query
name: name name: name
...@@ -167,6 +186,24 @@ paths: ...@@ -167,6 +186,24 @@ paths:
$ref: 'SwarmCommon.yaml#/components/schemas/FileName' $ref: 'SwarmCommon.yaml#/components/schemas/FileName'
required: false required: false
description: Filename description: Filename
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
type: boolean
required: false
description: Represents the pinning state of the file
- in: header
name: swarm-encrypt
schema:
type: boolean
required: false
description: Represents the encrypting state of the file
requestBody: requestBody:
content: content:
multipart/form-data: multipart/form-data:
...@@ -198,8 +235,8 @@ paths: ...@@ -198,8 +235,8 @@ paths:
'/files/{reference}': '/files/{reference}':
get: get:
summary: 'Get referenced file' summary: 'Get referenced file'
tags: tags:
- 'Endpoints on local bee node' - File
parameters: parameters:
- in: path - in: path
name: reference name: reference
...@@ -215,7 +252,7 @@ paths: ...@@ -215,7 +252,7 @@ paths:
schema: schema:
type: string type: string
format: binary format: binary
'400': '400':
$ref: 'SwarmCommon.yaml#/components/responses/400' $ref: 'SwarmCommon.yaml#/components/responses/400'
'404': '404':
...@@ -224,3 +261,192 @@ paths: ...@@ -224,3 +261,192 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
'/dirs':
post:
summary: 'Upload a collection'
tags:
- Collection
parameters:
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
type: boolean
required: false
description: Represents the pinning state of the collection
- in: header
name: swarm-encrypt
schema:
type: boolean
required: false
description: Represents the encrypting state of the collection
requestBody:
content:
application/x-tar:
schema:
type: string
format: binary
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/ReferenceResponse'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/bzz/{reference}/{path}':
get:
summary: 'Get referenced file from a collection of files'
tags:
- Collection
parameters:
- in: path
name: reference
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference'
required: true
description: Swarm address of content
- in: path
name: path
schema:
type: string
required: true
description: Path to the file in the collection.
- in: query
name: targets
schema:
type: string
required: false
description: Global pinning targets prefix
responses:
'200':
description: Ok
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/tags':
post:
summary: 'Create Tag'
tags:
- Tag
parameters:
- in: query
name: name
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/TagName'
required: true
description: Tagname
responses:
'200':
description: New Tag Info
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/tags/{uid}':
get:
summary: 'Get Tag information using Uid'
tags:
- Tag
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
responses:
'200':
description: Tag info
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
delete:
summary: 'Delete Tag information using Uid'
tags:
- Tag
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
responses:
'204':
$ref: 'SwarmCommon.yaml#/components/responses/204'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
patch:
summary: 'Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid'
tags:
- Tag
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
requestBody:
description: Can contain swarm hash to use for the tag
required: false
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Address'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Status'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
\ No newline at end of file
openapi/SwarmCommon.yaml
View file @ a1175610
...@@ -36,7 +36,7 @@ components: ...@@ -36,7 +36,7 @@ components:
$ref: '#/components/schemas/SwarmAddress' $ref: '#/components/schemas/SwarmAddress'
balance: balance:
type: integer type: integer
Balances: Balances:
type: object type: object
properties: properties:
...@@ -44,7 +44,7 @@ components: ...@@ -44,7 +44,7 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/Balance' $ref: '#/components/schemas/Balance'
BzzChunksPinned: BzzChunksPinned:
type: object type: object
properties: properties:
...@@ -94,7 +94,7 @@ components: ...@@ -94,7 +94,7 @@ components:
example: "2020-06-11T11:26:42.6969797+02:00" example: "2020-06-11T11:26:42.6969797+02:00"
Duration: Duration:
description: Go time.Duration format description: Go time.Duration format
type: string type: string
example: "5.0018ms" example: "5.0018ms"
...@@ -106,10 +106,10 @@ components: ...@@ -106,10 +106,10 @@ components:
properties: properties:
hash: hash:
$ref: '#/components/schemas/SwarmAddress' $ref: '#/components/schemas/SwarmAddress'
MultiAddress: MultiAddress:
type: string type: string
NewTagResponse: NewTagResponse:
type: object type: object
properties: properties:
...@@ -135,11 +135,11 @@ components: ...@@ -135,11 +135,11 @@ components:
type: string type: string
startedAt: startedAt:
$ref: '#/components/schemas/DateTime' $ref: '#/components/schemas/DateTime'
P2PUnderlay: P2PUnderlay:
type: string type: string
example: "/ip4/127.0.0.1/tcp/7070/p2p/16Uiu2HAmTm17toLDaPYzRyjKn27iCB76yjKnJ5DjQXneFmifFvaX" example: "/ip4/127.0.0.1/tcp/7070/p2p/16Uiu2HAmTm17toLDaPYzRyjKn27iCB76yjKnJ5DjQXneFmifFvaX"
Peers: Peers:
type: object type: object
properties: properties:
...@@ -158,7 +158,7 @@ components: ...@@ -158,7 +158,7 @@ components:
ProblemDetails: ProblemDetails:
type: string type: string
ReferenceResponse: ReferenceResponse:
type: object type: object
properties: properties:
...@@ -189,7 +189,7 @@ components: ...@@ -189,7 +189,7 @@ components:
type: string type: string
pattern: '^[A-Fa-f0-9]{64}$' pattern: '^[A-Fa-f0-9]{64}$'
example: "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f" example: "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
SwarmEncryptedReference: SwarmEncryptedReference:
type: string type: string
pattern: '^[A-Fa-f0-9]{128}$' pattern: '^[A-Fa-f0-9]{128}$'
...@@ -206,7 +206,16 @@ components: ...@@ -206,7 +206,16 @@ components:
Uid: Uid:
type: integer type: integer
WelcomeMessage:
type: object
properties:
welcome_message:
type: string
responses: responses:
'204':
description: The resource was deleted successfully.
'400': '400':
description: Bad request description: Bad request
content: content:
...@@ -225,5 +234,5 @@ components: ...@@ -225,5 +234,5 @@ components:
application/problem+json: application/problem+json:
schema: schema:
$ref: '#/components/schemas/ProblemDetails' $ref: '#/components/schemas/ProblemDetails'
openapi/SwarmDebug.yaml
View file @ a1175610
...@@ -23,12 +23,12 @@ servers: ...@@ -23,12 +23,12 @@ servers:
default: 6060 default: 6060
description: Service port provided in bee node config description: Service port provided in bee node config
paths: paths:
'/addresses': '/addresses':
get: get:
summary: Get overlay and underlay addresses of the node summary: Get overlay and underlay addresses of the node
tags: tags:
- Swarm Debug Endpoints - Connectivity
responses: responses:
'200': '200':
description: Own node underlay and overlay addresses description: Own node underlay and overlay addresses
...@@ -45,7 +45,7 @@ paths: ...@@ -45,7 +45,7 @@ paths:
get: get:
summary: Get the balances with all known peers summary: Get the balances with all known peers
tags: tags:
- Swarm Debug Endpoints - Balance
responses: responses:
'200': '200':
description: Own balances with all known peers description: Own balances with all known peers
...@@ -62,7 +62,7 @@ paths: ...@@ -62,7 +62,7 @@ paths:
get: get:
summary: Get the balances with a specific peer summary: Get the balances with a specific peer
tags: tags:
- Swarm Debug Endpoints - Balance
parameters: parameters:
- in: path - in: path
name: address name: address
...@@ -88,14 +88,14 @@ paths: ...@@ -88,14 +88,14 @@ paths:
get: get:
summary: Check if chunk at address exists locally summary: Check if chunk at address exists locally
tags: tags:
- Swarm Debug Endpoints - Chunk
parameters: parameters:
- in: path - in: path
name: address name: address
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress' $ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true required: true
description: Swarm address of chunk description: Swarm address of chunk
responses: responses:
'200': '200':
description: Chunk exists description: Chunk exists
...@@ -109,7 +109,31 @@ paths: ...@@ -109,7 +109,31 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/404' $ref: 'SwarmCommon.yaml#/components/responses/404'
default: default:
description: Default response description: Default response
delete:
summary: Delete a chunk from local storage
tags:
- Chunk
parameters:
- in: path
name: address
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true
description: Swarm address of chunk
responses:
'200':
description: Chunk exists
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Response'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
default:
description: Default response
'/chunks-pin/{address}': '/chunks-pin/{address}':
parameters: parameters:
- in: path - in: path
...@@ -117,11 +141,11 @@ paths: ...@@ -117,11 +141,11 @@ paths:
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress' $ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true required: true
description: Swarm address of chunk description: Swarm address of chunk
post: post:
summary: Pin chunk with given address summary: Pin chunk with given address
tags: tags:
- Swarm Debug Endpoints - Chunk pinning
responses: responses:
'200': '200':
description: Pinning chunk with address description: Pinning chunk with address
...@@ -138,7 +162,7 @@ paths: ...@@ -138,7 +162,7 @@ paths:
delete: delete:
summary: Unpin chunk with given address summary: Unpin chunk with given address
tags: tags:
- Swarm Debug Endpoints - Chunk pinning
responses: responses:
'200': '200':
description: Unpinning chunk with address description: Unpinning chunk with address
...@@ -155,7 +179,7 @@ paths: ...@@ -155,7 +179,7 @@ paths:
get: get:
summary: Get pinning status of chunk with given address summary: Get pinning status of chunk with given address
tags: tags:
- Swarm Debug Endpoints - Chunk pinning
responses: responses:
'200': '200':
description: Pinning state of chunk with address description: Pinning state of chunk with address
...@@ -167,12 +191,12 @@ paths: ...@@ -167,12 +191,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
'/chunks-pin/': '/chunks-pin/':
get: get:
summary: Get list of pinned chunks summary: Get list of pinned chunks
tags: tags:
- Swarm Debug Endpoints - Chunk pinning
responses: responses:
'200': '200':
description: List of pinned chunks description: List of pinned chunks
...@@ -184,12 +208,12 @@ paths: ...@@ -184,12 +208,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
'/connect/{multiAddress}': '/connect/{multiAddress}':
post: post:
summary: Connect to address summary: Connect to address
tags: tags:
- Swarm Debug Endpoints - Connectivity
parameters: parameters:
- in: path - in: path
allowReserved: true allowReserved: true
...@@ -216,7 +240,7 @@ paths: ...@@ -216,7 +240,7 @@ paths:
get: get:
summary: Get health of node summary: Get health of node
tags: tags:
- Swarm Debug Endpoints - Status
responses: responses:
'200': '200':
description: Health State of node description: Health State of node
...@@ -226,12 +250,12 @@ paths: ...@@ -226,12 +250,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/schemas/Status' $ref: 'SwarmCommon.yaml#/components/schemas/Status'
default: default:
description: Default response description: Default response
'/peers': '/peers':
get: get:
summary: Get a list of peers summary: Get a list of peers
tags: tags:
- Swarm Debug Endpoints - Connectivity
responses: responses:
'200': '200':
description: Returns overlay addresses of connected peers description: Returns overlay addresses of connected peers
...@@ -246,14 +270,14 @@ paths: ...@@ -246,14 +270,14 @@ paths:
delete: delete:
summary: Remove peer summary: Remove peer
tags: tags:
- Swarm Debug Endpoints - Connectivity
parameters: parameters:
- in: path - in: path
name: address name: address
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress' $ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true required: true
description: Swarm address of peer description: Swarm address of peer
responses: responses:
'200': '200':
description: Disconnected peer description: Disconnected peer
...@@ -267,12 +291,12 @@ paths: ...@@ -267,12 +291,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
'/pingpong/{peer-id}': '/pingpong/{peer-id}':
post: post:
summary: Try connection to node summary: Try connection to node
tags: tags:
- Swarm Debug Endpoints - Connectivity
parameters: parameters:
- in: path - in: path
name: peer-id name: peer-id
...@@ -295,13 +319,12 @@ paths: ...@@ -295,13 +319,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
'/readiness': '/readiness':
get: get:
summary: Get readiness state of node summary: Get readiness state of node
tags: tags:
- Swarm Debug Endpoints - Status
responses: responses:
'200': '200':
description: Health State of node description: Health State of node
...@@ -311,68 +334,55 @@ paths: ...@@ -311,68 +334,55 @@ paths:
$ref: 'SwarmCommon.yaml#/components/schemas/Status' $ref: 'SwarmCommon.yaml#/components/schemas/Status'
default: default:
description: Default response description: Default response
'/tags': '/topology':
post: get:
summary: 'Create Tag' description: Get topology of known network
tags: tags:
- Swarm Debug Endpoints - Connectivity
parameters:
- in: query
name: name
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/TagName'
required: true
description: Tagname
responses: responses:
'200': '200':
description: New Tag Info description: Swarm topology of the bee node
content: content:
application/json: application/json:
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse' $ref: 'SwarmCommon.yaml#/components/schemas/BzzTopology'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/tags/{uid}': '/welcome-message':
get: get:
summary: 'Get Tag information using Uid' summary: Get configured P2P welcome message
tags: tags:
- Swarm Debug Endpoints - Connectivity
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
responses: responses:
'200': '200':
description: Tag info description: Welcome message
content: content:
application/json: application/json:
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse' $ref: 'SwarmCommon.yaml#/components/schemas/WelcomeMessage'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500': '500':
$ref: 'SwarmCommon.yaml#/components/responses/500' $ref: 'SwarmCommon.yaml#/components/responses/500'
default: default:
description: Default response description: Default response
post:
'/topology': summary: Set P2P welcome message
get:
description: Get topology of known network
tags: tags:
- Swarm Debug Endpoints - Connectivity
requestBody:
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/WelcomeMessage'
responses: responses:
'200': '200':
description: Swarm topology of the bee node description: OK
content: content:
application/json: application/json:
schema: schema:
$ref: 'SwarmCommon.yaml#/components/schemas/BzzTopology' $ref: 'SwarmCommon.yaml#/components/schemas/Status'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment