From cbbd3428acc818f69a40e608c4a125e3c41e3c9b Mon Sep 17 00:00:00 2001
From: Danilo Tuler <tuler@pobox.com>
Date: Mon, 4 Dec 2023 15:45:18 -0300
Subject: [PATCH] feat: openapi for application management

---
 api/openapi.yaml | 209 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 209 insertions(+)
 create mode 100644 api/openapi.yaml

diff --git a/api/openapi.yaml b/api/openapi.yaml
new file mode 100644
index 000000000..f6e2f74b7
--- /dev/null
+++ b/api/openapi.yaml
@@ -0,0 +1,209 @@
+openapi: 3.0.0
+info:
+  title: Cartesi Rollups Node Management API
+  description: |-
+    This is a management API for the Cartesi Rollups Node. It allows to dinamically add and remove applications managed by the node, or query the list of managed applications.
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  version: 1.0.0
+tags:
+  - name: applications
+    description: Cartesi applications
+paths:
+  /applications:
+    get:
+      tags:
+        - applications
+      summary: Fetches list of applications managed by the node
+      description: List of managed applications
+      operationId: getApplications
+      parameters:
+        - name: status
+          in: query
+          description: Filter by application status
+          schema:
+            type: string
+            enum:
+              - started
+              - starting
+              - stopping
+              - stopped
+        - name: offset
+          in: query
+          description: Items to skip for pagination
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+        - name: limit
+          in: query
+          description: Maximum number of items per page
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            default: 100
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/PaginatedResult"
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Application"
+  /applications/{address}:
+    get:
+      tags:
+        - applications
+      summary: Find application by address
+      description: Returns a single application by its address
+      operationId: getApplicationByAddress
+      parameters:
+        - name: address
+          in: path
+          description: Address of application to return
+          required: true
+          schema:
+            type: string
+            format: address
+            example: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+            pattern: "^0x([0-9a-fA-F]{40})$"
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Application"
+        "400":
+          description: Invalid address supplied
+        "404":
+          description: Application not found
+    put:
+      tags:
+        - applications
+      summary: Adds an application
+      description: Adds an application by its address
+      operationId: addApplication
+      parameters:
+        - name: address
+          in: path
+          description: Application address
+          required: true
+          schema:
+            type: string
+            format: address
+            example: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+            pattern: "^0x([0-9a-fA-F]{40})$"
+      requestBody:
+        $ref: "#/components/requestBodies/Application"
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Application"
+    delete:
+      tags:
+        - applications
+      summary: Deletes an application
+      description: delete an application
+      operationId: deleteApplication
+      parameters:
+        - name: address
+          in: path
+          description: Application address to delete
+          required: true
+          schema:
+            type: string
+            format: address
+            example: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+            pattern: "^0x([0-9a-fA-F]{40})$"
+      responses:
+        "202":
+          description: Delete request accepted
+        "400":
+          description: Invalid address value
+        "404":
+          description: Application not found
+components:
+  schemas:
+    PaginatedResult:
+      type: object
+      properties:
+        total_count:
+          type: integer
+        offset:
+          type: integer
+        limit:
+          type: integer
+        data:
+          type: array
+          items: {}
+      required:
+        - total_count
+        - offset
+        - limit
+        - data
+    Application:
+      required:
+        - address
+        - blockNumber
+        - templateHash
+        - snapshotUrl
+      type: object
+      properties:
+        address:
+          type: string
+          format: address
+          example: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+          pattern: "^0x([0-9a-fA-F]{40})$"
+        blockNumber:
+          type: integer
+          example: 456311
+        templateHash:
+          type: string
+          format: hash
+          pattern: "^([0-9a-fA-F]{64})$"
+          example: "9a8d6ce861c71b592c236013b5c3fa167501431def4ad86ff59a3b12aa331dfc"
+        snapshotUrl:
+          type: string
+          format: url
+        status:
+          type: string
+          description: application status
+          enum:
+            - started
+            - starting
+            - stopping
+            - stopped
+            - error
+  requestBodies:
+    Application:
+      description: Application to be added to the node
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              blockNumber:
+                type: integer
+                example: 456311
+              templateHash:
+                type: string
+                format: hash
+                pattern: "^([0-9a-fA-F]{64})$"
+                example: "9a8d6ce861c71b592c236013b5c3fa167501431def4ad86ff59a3b12aa331dfc"
+              snapshotUrl:
+                type: string
+                format: url