Skip to content

M
mybee
Commit 4909a7f5 authored by Adam Uhlíř's avatar Adam Uhlíř Committed by GitHub
Browse files
Options

docs: gateway mode forbidden and tweaks (#2325)

parent 3a61f8d4
Hide whitespace changes
Inline Side-by-side
Showing with 60 additions and 40 deletions
openapi/Swarm.yaml
View file @ 4909a7f5
openapi: 3.0.3 openapi: 3.0.3
info: info:
version: 0.6.0 version: 1.0.0
title: Swarm API title: Swarm API
description: "A list of the currently provided Interfaces to interact with the swarm, implementing file operations and sending messages" description: "A list of the currently provided Interfaces to interact with the swarm, implementing file operations and sending messages"
...@@ -10,7 +10,7 @@ security: ...@@ -10,7 +10,7 @@ security:
externalDocs: externalDocs:
description: Browse the documentation @ the Swarm Docs description: Browse the documentation @ the Swarm Docs
url: "https://docs.swarm.eth" url: "https://docs.ethswarm.org"
servers: servers:
- url: "http://{apiRoot}:{port}/v1" - url: "http://{apiRoot}:{port}/v1"
...@@ -62,7 +62,7 @@ paths: ...@@ -62,7 +62,7 @@ paths:
"402": "402":
$ref: "SwarmCommon.yaml#/components/responses/402" $ref: "SwarmCommon.yaml#/components/responses/402"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -157,6 +157,8 @@ paths: ...@@ -157,6 +157,8 @@ paths:
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"402": "402":
$ref: "SwarmCommon.yaml#/components/responses/402" $ref: "SwarmCommon.yaml#/components/responses/402"
"403":
$ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -171,8 +173,7 @@ paths: ...@@ -171,8 +173,7 @@ paths:
A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files
uploaded as a multipart request, the swarm-index-document header should be used with the name of the file." uploaded as a multipart request, the swarm-index-document header should be used with the name of the file."
tags: tags:
- File - BZZ
- Collection
parameters: parameters:
- in: query - in: query
name: name name: name
...@@ -223,7 +224,7 @@ paths: ...@@ -223,7 +224,7 @@ paths:
"402": "402":
$ref: "SwarmCommon.yaml#/components/responses/402" $ref: "SwarmCommon.yaml#/components/responses/402"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -233,15 +234,14 @@ paths: ...@@ -233,15 +234,14 @@ paths:
patch: patch:
summary: "Reupload a root hash to the network" summary: "Reupload a root hash to the network"
tags: tags:
- Reupload file - BZZ
- Reupload collection
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: Root hash of content description: "Root hash of content (can be of any type: collection, file, chunk)"
responses: responses:
"200": "200":
description: Ok description: Ok
...@@ -252,7 +252,7 @@ paths: ...@@ -252,7 +252,7 @@ paths:
get: get:
summary: "Get file or index document from a collection of files" summary: "Get file or index document from a collection of files"
tags: tags:
- Collection - BZZ
parameters: parameters:
- in: path - in: path
name: reference name: reference
...@@ -287,7 +287,7 @@ paths: ...@@ -287,7 +287,7 @@ paths:
get: get:
summary: "Get referenced file from a collection of files" summary: "Get referenced file from a collection of files"
tags: tags:
- Collection - BZZ
parameters: parameters:
- in: path - in: path
name: reference name: reference
...@@ -354,7 +354,7 @@ paths: ...@@ -354,7 +354,7 @@ paths:
schema: schema:
$ref: "SwarmCommon.yaml#/components/schemas/TagsList" $ref: "SwarmCommon.yaml#/components/schemas/TagsList"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -377,7 +377,7 @@ paths: ...@@ -377,7 +377,7 @@ paths:
schema: schema:
$ref: "SwarmCommon.yaml#/components/schemas/NewTagResponse" $ref: "SwarmCommon.yaml#/components/schemas/NewTagResponse"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -405,7 +405,7 @@ paths: ...@@ -405,7 +405,7 @@ paths:
"400": "400":
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"404": "404":
$ref: "SwarmCommon.yaml#/components/responses/404" $ref: "SwarmCommon.yaml#/components/responses/404"
"500": "500":
...@@ -429,7 +429,7 @@ paths: ...@@ -429,7 +429,7 @@ paths:
"400": "400":
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"404": "404":
$ref: "SwarmCommon.yaml#/components/responses/404" $ref: "SwarmCommon.yaml#/components/responses/404"
"500": "500":
...@@ -462,7 +462,7 @@ paths: ...@@ -462,7 +462,7 @@ paths:
schema: schema:
$ref: "SwarmCommon.yaml#/components/schemas/Status" $ref: "SwarmCommon.yaml#/components/schemas/Status"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"404": "404":
$ref: "SwarmCommon.yaml#/components/responses/404" $ref: "SwarmCommon.yaml#/components/responses/404"
"500": "500":
...@@ -481,7 +481,7 @@ paths: ...@@ -481,7 +481,7 @@ paths:
post: post:
summary: Pin the root hash with the given reference summary: Pin the root hash with the given reference
tags: tags:
- Root hash pinning - Pinning
responses: responses:
"200": "200":
description: Pin already exists, so no operation description: Pin already exists, so no operation
...@@ -498,7 +498,7 @@ paths: ...@@ -498,7 +498,7 @@ paths:
"400": "400":
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"404": "404":
$ref: "SwarmCommon.yaml#/components/responses/404" $ref: "SwarmCommon.yaml#/components/responses/404"
"500": "500":
...@@ -508,7 +508,7 @@ paths: ...@@ -508,7 +508,7 @@ paths:
delete: delete:
summary: Unpin the root hash with the given reference summary: Unpin the root hash with the given reference
tags: tags:
- Root hash pinning - Pinning
responses: responses:
"200": "200":
description: Unpinning root hash with reference description: Unpinning root hash with reference
...@@ -519,7 +519,7 @@ paths: ...@@ -519,7 +519,7 @@ paths:
"400": "400":
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -527,7 +527,7 @@ paths: ...@@ -527,7 +527,7 @@ paths:
get: get:
summary: Get pinning status of the root hash with the given reference summary: Get pinning status of the root hash with the given reference
tags: tags:
- Root hash pinning - Pinning
responses: responses:
"200": "200":
description: Reference of the pinned root hash description: Reference of the pinned root hash
...@@ -538,7 +538,7 @@ paths: ...@@ -538,7 +538,7 @@ paths:
"400": "400":
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"404": "404":
$ref: "SwarmCommon.yaml#/components/responses/404" $ref: "SwarmCommon.yaml#/components/responses/404"
"500": "500":
...@@ -550,7 +550,7 @@ paths: ...@@ -550,7 +550,7 @@ paths:
get: get:
summary: Get the list of pinned root hash references summary: Get the list of pinned root hash references
tags: tags:
- Root hash pinning - Pinning
responses: responses:
"200": "200":
description: List of pinned root hash references description: List of pinned root hash references
...@@ -559,7 +559,7 @@ paths: ...@@ -559,7 +559,7 @@ paths:
schema: schema:
$ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReferencesList" $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReferencesList"
"403": "403":
$ref: "SwarmCommon.yaml#/components/responses/403" $ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -597,6 +597,8 @@ paths: ...@@ -597,6 +597,8 @@ paths:
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"402": "402":
$ref: "SwarmCommon.yaml#/components/responses/402" $ref: "SwarmCommon.yaml#/components/responses/402"
"403":
$ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -617,6 +619,8 @@ paths: ...@@ -617,6 +619,8 @@ paths:
responses: responses:
"200": "200":
description: Returns a WebSocket with a subscription for incoming message data on the requested topic. description: Returns a WebSocket with a subscription for incoming message data on the requested topic.
"403":
$ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -660,6 +664,8 @@ paths: ...@@ -660,6 +664,8 @@ paths:
$ref: "SwarmCommon.yaml#/components/responses/401" $ref: "SwarmCommon.yaml#/components/responses/401"
"402": "402":
$ref: "SwarmCommon.yaml#/components/responses/402" $ref: "SwarmCommon.yaml#/components/responses/402"
"403":
$ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -704,6 +710,8 @@ paths: ...@@ -704,6 +710,8 @@ paths:
$ref: "SwarmCommon.yaml#/components/responses/401" $ref: "SwarmCommon.yaml#/components/responses/401"
"402": "402":
$ref: "SwarmCommon.yaml#/components/responses/402" $ref: "SwarmCommon.yaml#/components/responses/402"
"403":
$ref: "SwarmCommon.yaml#/components/responses/GatewayForbidden"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -802,7 +810,8 @@ paths: ...@@ -802,7 +810,8 @@ paths:
"/stamps/{amount}/{depth}": "/stamps/{amount}/{depth}":
post: post:
summary: Buy a new postage batch. Be aware, this endpoint create an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance! summary: Buy a new postage batch.
description: Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!
deprecated: true deprecated: true
tags: tags:
- Postage Stamps - Postage Stamps
......
openapi/SwarmCommon.yaml
View file @ 4909a7f5
openapi: 3.0.3 openapi: 3.0.3
info: info:
version: 0.6.0 version: 1.0.0
title: Common Data Types title: Common Data Types
description: | description: |
\*****bzzz***** \*****bzzz*****
...@@ -554,7 +554,10 @@ components: ...@@ -554,7 +554,10 @@ components:
schema: schema:
type: boolean type: boolean
required: false required: false
description: Represents the pinning state of the chunk description: >
Represents if the uploaded data should be also locally pinned on the node.
Warning! Not available for nodes that run in Gateway mode!
SwarmEncryptParameter: SwarmEncryptParameter:
in: header in: header
...@@ -562,7 +565,10 @@ components: ...@@ -562,7 +565,10 @@ components:
schema: schema:
type: boolean type: boolean
required: false required: false
description: Represents the encrypting state of the file description: >
Represents the encrypting state of the file
Warning! Not available for nodes that run in Gateway mode!
ContentTypePreserved: ContentTypePreserved:
in: header in: header
...@@ -603,7 +609,7 @@ components: ...@@ -603,7 +609,7 @@ components:
description: "ID of Postage Batch that is used to upload data with" description: "ID of Postage Batch that is used to upload data with"
required: true required: true
schema: schema:
$ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" $ref: "#/components/schemas/SwarmAddress"
responses: responses:
"204": "204":
...@@ -626,12 +632,6 @@ components: ...@@ -626,12 +632,6 @@ components:
application/problem+json: application/problem+json:
schema: schema:
$ref: "#/components/schemas/ProblemDetails" $ref: "#/components/schemas/ProblemDetails"
"403":
description: Forbidden
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
"404": "404":
description: Not Found description: Not Found
content: content:
...@@ -644,3 +644,10 @@ components: ...@@ -644,3 +644,10 @@ components:
application/problem+json: application/problem+json:
schema: schema:
$ref: "#/components/schemas/ProblemDetails" $ref: "#/components/schemas/ProblemDetails"
"GatewayForbidden":
description: "Endpoint or header (pinning or encryption headers) forbidden in Gateway mode"
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
\ No newline at end of file
openapi/SwarmDebug.yaml
View file @ 4909a7f5
openapi: 3.0.3 openapi: 3.0.3
info: info:
version: 0.6.0 version: 1.0.0
title: Bee Debug API title: Bee Debug API
description: "A list of the currently provided debug interfaces to interact with the bee node" description: "A list of the currently provided debug interfaces to interact with the bee node"
...@@ -9,7 +9,7 @@ security: ...@@ -9,7 +9,7 @@ security:
externalDocs: externalDocs:
description: Browse the documentation @ the Swarm Docs description: Browse the documentation @ the Swarm Docs
url: "https://docs.swarm.eth" url: "https://docs.ethswarm.org"
servers: servers:
- url: "http://{apiRoot}:{port}" - url: "http://{apiRoot}:{port}"
...@@ -663,8 +663,6 @@ paths: ...@@ -663,8 +663,6 @@ paths:
$ref: "SwarmCommon.yaml#/components/schemas/NewTagDebugResponse" $ref: "SwarmCommon.yaml#/components/schemas/NewTagDebugResponse"
"400": "400":
$ref: "SwarmCommon.yaml#/components/responses/400" $ref: "SwarmCommon.yaml#/components/responses/400"
"403":
$ref: "SwarmCommon.yaml#/components/responses/403"
"500": "500":
$ref: "SwarmCommon.yaml#/components/responses/500" $ref: "SwarmCommon.yaml#/components/responses/500"
default: default:
...@@ -804,7 +802,8 @@ paths: ...@@ -804,7 +802,8 @@ paths:
"/stamps/{amount}/{depth}": "/stamps/{amount}/{depth}":
post: post:
summary: Buy a new postage batch. Be aware, this endpoint create an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance! summary: Buy a new postage batch.
description: Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!
tags: tags:
- Postage Stamps - Postage Stamps
parameters: parameters:
...@@ -826,6 +825,11 @@ paths: ...@@ -826,6 +825,11 @@ paths:
type: string type: string
required: false required: false
description: An optional label for this batch description: An optional label for this batch
- in: header
name: immutable
schema:
type: boolean
required: false
- $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
responses: responses:
"201": "201":
......
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