Merge pull request #3216 from HHS/OPS-3215/can-history-api-spec

docs: update spec for /can-history
HHS · Dec 16, 2024 · 138b346 · 138b346
2 parents ed4d0a8 + e0c587b
commit 138b346
Showing 1 changed file with 91 additions and 0 deletions.
diff --git a/backend/openapi.yml b/backend/openapi.yml
@@ -877,6 +877,42 @@ paths:
           description: Unauthorized
         "404":
           description: Unable to find specified CANFundingBudget
+  /api/v1/can-history:
+    get:
+      tags:
+        - CAN History
+      operationId: getAllCANHistory
+      summary: Get a list all CAN history objects
+      parameters:
+        - $ref: "#/components/parameters/simulatedError"
+        - name: can_id
+          in: query
+          schema:
+            type: integer
+          example: 1
+        - name: offset
+          in: query
+          schema:
+            type: integer
+          example: 0
+        - name: limit
+          in: query
+          schema:
+              type: integer
+              default: 10
+          example: 10
+      description: Get CANHistory
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CANHistoryList"
+        "401":
+          description: Insufficient Privileges to use this endpoint.
+        "403":
+            description: Forbidden
   /api/v1/portfolios:
     get:
       tags:
@@ -2811,6 +2847,61 @@ components:
         - id
         - portfolio_id
         - number
+    CANHistoryList:
+      description: A list of CAN objects with their history
+      type: array
+      items:
+        anyOf:
+          - $ref: "#/components/schemas/CANHistoryItem"
+    CANHistoryItem:
+        description: A single CAN object with its history
+        type: object
+        properties:
+          id:
+            type: integer
+            description: The unique identifier for the history record.
+            example: 2
+          can_id:
+            type: integer
+            description: FK to the CAN object that the history record is associated with.
+            example: 3
+          ops_event_id:
+            type: integer
+            description: FK to the OPS event that triggered the history record.
+            example: 4
+          history_title:
+            type: string
+            description: The title of the history event in Markdown format.
+            example: "Nickname Edited"
+          history_message:
+            type: string
+            description: The message that describes the history event in Markdown format.
+            example: "Omkar Kuber edited the nickname from 'CAN 1' to 'CAN 2'"
+          timestamp:
+            type: string
+            description: The timestamp of when the history event was created (different than created_on).
+            format: date-time
+            example: "2023-09-01T00:00:00.000000Z"
+          history_type:
+            type: string
+            enum:
+              - CAN_DATA_IMPORT
+              - CAN_NICKNAME_EDITED
+              - CAN_DESCRIPTION_EDITED
+              - CAN_FUNDING_CREATED
+              - CAN_RECEIVED_CREATED
+              - CAN_FUNDING_EDITED
+              - CAN_RECEIVED_EDITED
+              - CAN_FUNDING_DELETED
+              - CAN_RECEIVED_DELETED
+              - CAN_PORTFOLIO_CREATED
+              - CAN_PORTFOLIO_DELETED
+              - CAN_PORTFOLIO_EDITED
+              - CAN_DIVISION_CREATED
+              - CAN_DIVISION_DELETED
+              - CAN_DIVISION_EDITED
+              - CAN_CARRY_FORWARD_CALCULATED
+            example: "CAN_NICKNAME_EDITED"
     FundingReceived:
       description: Funding Received Object
       type: object