diff --git a/openapi/Swarm.yaml b/openapi/Swarm.yaml index 666f3e8c4..61b446d10 100644 --- a/openapi/Swarm.yaml +++ b/openapi/Swarm.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: - version: 5.0.0 + version: 5.2.0 title: Bee API description: "A list of the currently provided Interfaces to interact with the swarm, implementing file operations and sending messages" @@ -13,14 +13,23 @@ externalDocs: url: "https://docs.ethswarm.org" servers: - - url: http://{apiRoot}:{port} + - url: "http://{apiRoot}:{port}/v1" variables: apiRoot: - default: localhost + default: "localhost" description: Base address of the local bee node main API port: default: "1633" description: Service port provided in bee node config + - url: "http://{apiRoot}:{port}" + variables: + apiRoot: + default: "localhost" + description: Base address of the local bee node main API + port: + default: "1633" + description: Service port provided in bee node config + paths: "/auth": post: @@ -111,6 +120,11 @@ paths: $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter" name: swarm-encrypt required: false + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" + name: swarm-redundancy-level + required: false requestBody: content: @@ -149,6 +163,10 @@ paths: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true description: Swarm address reference to content + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" responses: "200": description: Retrieved content specified by reference @@ -201,7 +219,7 @@ paths: "/chunks/stream": get: summary: "Upload stream of chunks" - description: "Returns a WebSocket connection on which stream of chunks can be uploaded. Each chunk sent is acknowledged using a binary response `0` which serves as confirmation of upload of single chunk. Chunks should be packaged as binary messages for uploading. If a tag is specified, the chunks will be streamed into the localstore and then uploaded to the network once the stream is closed. If a tag is not specified, the chunks will bypass the localstore and be directly uploaded to the network through the stream as they arrive." + description: "Returns a WebSocket connection on which stream of chunks can be uploaded. Each chunk sent is acknowledged using a binary response `0` which serves as confirmation of upload of single chunk. Chunks should be packaged as binary messages for uploading. If a tag is specified, the chunks will be streamed into local storage and then be uploaded to the network once the stream is closed. If a tag is not specified, the chunks will bypass local storage and be directly uploaded to the network through the stream as they arrive." tags: - Chunk parameters: @@ -240,6 +258,7 @@ paths: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmErrorDocumentParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" requestBody: content: multipart/form-data: @@ -291,6 +310,10 @@ paths: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true description: Swarm address of content + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" responses: "200": description: Ok @@ -328,6 +351,9 @@ paths: type: string required: true description: Path to the file in the collection. + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" + - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" responses: "200": description: Ok @@ -659,6 +685,14 @@ paths: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" name: swarm-postage-batch-id required: true + requestBody: + required: true + description: The SOC binary data is composed of the span (8 bytes) and the at most 4KB payload. + content: + application/octet-stream: + schema: + type: string + format: binary responses: "201": description: Created @@ -743,6 +777,12 @@ paths: type: integer required: false description: "Timestamp of the update (default: now)" + - in: query + name: after + schema: + type: integer + required: false + description: "Start index (default: 0)" - in: query name: type schema: @@ -1041,6 +1081,11 @@ paths: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true description: Swarm address of chunk + - in: header + schema: + $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" + name: swarm-cache + required: false responses: "200": description: Retrieved chunk content @@ -1636,12 +1681,6 @@ paths: description: Default response "/stamps": - parameters: - - in: query - name: all - schema: - type: string - description: Gets all stamps. Default is null. get: summary: Get stamps for this node description: This endpoint is available on the main API only if the node is spawned with the `--restricted` flag along with a bearer authentication token. @@ -1656,6 +1695,8 @@ paths: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatchesResponse" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response @@ -1682,6 +1723,8 @@ paths: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatch" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: @@ -1709,6 +1752,8 @@ paths: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PostageStampBuckets" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: diff --git a/openapi/SwarmCommon.yaml b/openapi/SwarmCommon.yaml index 7983a5e2a..43cc1d3ab 100644 --- a/openapi/SwarmCommon.yaml +++ b/openapi/SwarmCommon.yaml @@ -1,6 +1,6 @@ openapi: 3.0.3 info: - version: 3.2.3 + version: 3.2.6 title: Common Data Types description: | \*****bzzz***** @@ -470,8 +470,6 @@ components: type: boolean batchTTL: type: integer - expired: - type: boolean PostageBatchNoIssuer: type: object @@ -710,6 +708,8 @@ components: type: boolean isFullySynced: type: boolean + isHealthy: + type: boolean phase: type: string round: @@ -934,6 +934,52 @@ components: description: > Represents the encrypting state of the file + SwarmRedundancyLevelParameter: + in: header + name: swarm-redundancy-level + schema: + type: integer + enum: [0, 1, 2, 3, 4] + required: false + description: > + Add redundancy to the data being uploaded so that downloaders can download it with better UX. + 0 value is default and does not add any redundancy to the file. + + SwarmRedundancyStrategyParameter: + in: header + name: swarm-redundancy-strategy + schema: + type: integer + enum: [0, 1, 2, 3] + required: false + description: > + Specify the retrieve strategy on redundant data. + The mumbers stand for NONE, DATA, PROX and RACE, respectively. + Strategy NONE means no prefetching takes place. + Strategy DATA means only data chunks are prefetched. + Strategy PROX means only chunks that are close to the node are prefetched. + Strategy RACE means all chunks are prefetched: n data chunks and k parity chunks. The first n chunks to arrive are used to reconstruct the file. + Multiple strategies can be used in a fallback cascade if the swarm redundancy fallback mode is set to true. + The default strategy is NONE, DATA, falling back to PROX, falling back to RACE + + SwarmRedundancyFallbackModeParameter: + in: header + name: swarm-redundancy-fallback-mode + schema: + type: boolean + required: false + description: > + Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true. + + SwarmChunkRetrievalTimeoutParameter: + in: header + name: swarm-chunk-retrieval-timeout + schema: + $ref: "#/components/schemas/Duration" + required: false + description: > + Specify the timeout for chunk retrieval. The default is 30 seconds. + ContentTypePreserved: in: header name: Content-Type @@ -980,10 +1026,19 @@ components: name: swarm-deferred-upload schema: type: boolean - default: "true" + default: "false" required: false description: > - Determines if the uploaded data should be sent to the network immediately or in a deferred fashion. By default the upload will be deferred. + Determines if the uploaded data should be sent to the network immediately or in a deferred fashion. By default the upload will be direct. + + SwarmCache: + in: header + name: swarm-cache + schema: + type: boolean + default: "true" + required: false + description: "Determines if the download data should be cached on the node. By default the download will be cached" responses: "200": diff --git a/openapi/SwarmDebug.yaml b/openapi/SwarmDebug.yaml index 13ba75900..11d7b1a5f 100644 --- a/openapi/SwarmDebug.yaml +++ b/openapi/SwarmDebug.yaml @@ -1,6 +1,6 @@ openapi: 3.0.3 info: - version: 4.0.0 + version: 4.1.0 title: Bee Debug API description: "A list of the currently provided debug interfaces to interact with the bee node" @@ -12,13 +12,13 @@ externalDocs: url: "https://docs.ethswarm.org" servers: - - url: http://{apiRoot}:{port} + - url: "http://{apiRoot}:{port}" variables: apiRoot: - default: localhost + default: "localhost" description: Base address of the local bee node debug API port: - default: 1635 + default: "1635" description: Service port provided in bee node config paths: @@ -783,13 +783,6 @@ paths: description: Default response "/stamps": - parameters: - - in: query - name: all - schema: - type: string - required: false - description: Gets all stamps. Default is null. get: summary: Get stamps for this node tags: @@ -801,6 +794,8 @@ paths: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatchesResponse" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response @@ -824,6 +819,8 @@ paths: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatch" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: @@ -848,6 +845,8 @@ paths: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PostageStampBuckets" + "404": + $ref: "SwarmCommon.yaml#/components/responses/404" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: @@ -883,7 +882,6 @@ paths: schema: type: boolean required: false - - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" responses: "201": description: Returns the newly created postage batch ID