docs(act): add act api to openapi (#44)

docs(act): add incoming act headers to openapi docs(act): add act headers to upload endpoints in openapi docs(act): add act grantee list endpoints to openapi
Solar-Punk-Ltd · May 22, 2024 · b0dba7e · b0dba7e
1 parent c0fe597
commit b0dba7e
Show file tree

Hide file tree

Showing 3 changed files with 238 additions and 0 deletions.
diff --git a/openapi/Swarm.yaml b/openapi/Swarm.yaml
@@ -89,6 +89,135 @@ paths:
         default:
           description: Default response
 
+  "/grantee":
+    post:
+      summary: "Create grantee list"
+      tags:
+        - ACT
+      parameters:
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
+          name: swarm-postage-batch-id
+          required: true
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
+          name: swarm-tag
+          required: false
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
+          name: swarm-pin
+          required: false
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
+          name: swarm-deferred-upload
+          required: false
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
+          name: swarm-act-history-address
+          required: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesCreateRequest"
+      responses:
+        "201":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesOperationResponse"
+        "400":
+          $ref: "SwarmCommon.yaml#/components/responses/400"
+        "500":
+          $ref: "SwarmCommon.yaml#/components/responses/500"
+
+  "/grantee/{reference}":
+    get:
+      summary: "Get grantee list"
+      tags:
+        - ACT
+      parameters:
+        - in: path
+          name: reference
+          schema:
+            $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference"
+          required: true
+          description: Grantee list reference
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "SwarmCommon.yaml#/components/schemas/PublicKey"
+        "404":
+          $ref: "SwarmCommon.yaml#/components/responses/404"
+        "500":
+          $ref: "SwarmCommon.yaml#/components/responses/500"
+    patch:
+      summary: "Update grantee list"
+      description: "Add or remove grantees from an existing grantee list"
+      tags:
+        - ACT
+      parameters:
+        - in: path
+          name: reference
+          schema:
+            $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference"
+          required: true
+          description: Grantee list reference
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
+          name: swarm-act-history-address
+          required: true
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
+          name: swarm-postage-batch-id
+          required: true
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
+          name: swarm-tag
+          required: false
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
+          name: swarm-pin
+          required: false
+        - in: header
+          schema:
+            $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
+          name: swarm-deferred-upload
+          required: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesPatchRequest"
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesOperationResponse"
+        "400":
+          $ref: "SwarmCommon.yaml#/components/responses/400"
+        "500":
+          $ref: "SwarmCommon.yaml#/components/responses/500"
+
   "/bytes":
     post:
       summary: "Upload data"
@@ -167,6 +296,9 @@ paths:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Retrieved content specified by reference
@@ -190,6 +322,9 @@ paths:
             $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
           required: true
           description: Swarm address of chunk
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Chunk exists
@@ -208,6 +343,8 @@ paths:
       parameters:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       requestBody:
         description: Chunk binary data that has to have at least 8 bytes.
         content:
@@ -223,6 +360,8 @@ paths:
               description: Tag UID if it was passed to the request `swarm-tag` header.
               schema:
                 $ref: "SwarmCommon.yaml#/components/schemas/Uid"
+            "swarm-act-history-address":
+              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
           content:
             application/json:
               schema:
@@ -279,6 +418,8 @@ paths:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       requestBody:
         content:
           multipart/form-data:
@@ -305,6 +446,8 @@ paths:
               $ref: "SwarmCommon.yaml#/components/headers/SwarmTag"
             "etag":
               $ref: "SwarmCommon.yaml#/components/headers/ETag"
+            "swarm-act-history-address":
+              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
           content:
             application/json:
               schema:
@@ -334,6 +477,9 @@ paths:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Ok
@@ -363,6 +509,9 @@ paths:
             $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
           required: true
           description: Swarm address of chunk
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Chunk exists
@@ -749,6 +898,8 @@ paths:
             $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
           name: swarm-postage-batch-id
           required: true
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       requestBody:
         required: true
         description: The SOC binary data is composed of the span (8 bytes) and the at most 4KB payload.
@@ -764,6 +915,9 @@ paths:
             application/json:
               schema:
                 $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
+          headers:
+            "swarm-act-history-address":
+              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
         "400":
           $ref: "SwarmCommon.yaml#/components/responses/400"
         "401":
@@ -801,13 +955,18 @@ paths:
           description: "Feed indexing scheme (default: sequence)"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "201":
           description: Created
           content:
             application/json:
               schema:
                 $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
+          headers:
+            "swarm-act-history-address":
+              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
         "400":
           $ref: "SwarmCommon.yaml#/components/responses/400"
         "401":
@@ -1150,6 +1309,9 @@ paths:
             $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache"
           name: swarm-cache
           required: false
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Retrieved chunk content
@@ -1177,6 +1339,9 @@ paths:
             $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
           required: true
           description: Swarm address of chunk
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Chunk exists

diff --git a/openapi/SwarmCommon.yaml b/openapi/SwarmCommon.yaml
@@ -87,6 +87,36 @@ components:
         ghostBalance:
           $ref: "#/components/schemas/BigInt"
 
+    ActGranteesCreateRequest:
+      type: object
+      properties:
+        grantees:
+          type: array
+          items:
+            $ref: "#/components/schemas/PublicKey"
+
+    ActGranteesPatchRequest:
+      type: object
+      properties:
+        add:
+          type: array
+          items:
+            $ref: "#/components/schemas/PublicKey"
+          description: List of grantees to add
+        revoke:
+          type: array
+          items:
+            $ref: "#/components/schemas/PublicKey"
+          description: List of grantees to revoke future access from
+
+    ActGranteesOperationResponse:
+      type: object
+      properties:
+        ref:
+          $ref: "#/components/schemas/SwarmEncryptedReference"
+        historyref:
+          $ref: "#/components/schemas/SwarmEncryptedReference"
+
     Balance:
       type: object
       properties:
@@ -977,6 +1007,12 @@ components:
       schema:
         $ref: "#/components/schemas/HexString"
 
+    SwarmActHistoryAddress:
+      description: "Swarm address reference to the new ACT history entry"
+      schema:
+        $ref: "#/components/schemas/SwarmAddress"
+      required: false
+
     ETag:
       description: |
         The RFC7232 ETag header field in a response provides the current entity-
@@ -1137,6 +1173,40 @@ components:
       required: false
       description: "Determines if the download data should be cached on the node. By default the download will be cached"
 
+    SwarmAct:
+      in: header
+      name: swarm-act
+      schema:
+        type: boolean
+        default: "false"
+      required: false
+      description: "Determines if the uploaded data should be treated as ACT content"
+
+    SwarmActPublisher:
+      in: header
+      name: swarm-act-publisher
+      schema:
+        $ref: "#/components/schemas/PublicKey"
+      required: false
+      description: "ACT content publisher's public key"
+
+    SwarmActHistoryAddress:
+      in: header
+      name: swarm-act-history-address
+      schema:
+        $ref: "#/components/schemas/SwarmAddress"
+      required: false
+      description: "ACT history reference address"
+
+    SwarmActTimestamp:
+      in: header
+      name: swarm-act-timestamp
+      schema:
+        type: integer
+        format: int64
+      required: false
+      description: "ACT history Unix timestamp"
+
   responses:
     "200":
       description: OK.

diff --git a/openapi/SwarmDebug.yaml b/openapi/SwarmDebug.yaml
@@ -201,6 +201,9 @@ paths:
             $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
           required: true
           description: Swarm address of chunk
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
       responses:
         "200":
           description: Chunk exists