Merge pull request #541 from ethersphere/erasure-code

added updated openapi files
ethersphere · Dec 20, 2023 · 35b9d49 · 35b9d49
2 parents 50bfaad + 33dadf9
commit 35b9d49
Show file tree

Hide file tree

Showing 3 changed files with 125 additions and 27 deletions.
diff --git 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
@@ -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
@@ -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