[ENG-7331][WIP] V2 Project Reference PR

swagger-spec/actions/action_detail.yaml

@@ -0,0 +1,98 @@
+# /actions/{action_id}/:
+
+get:
+  summary: Retrieve an Action by ID
+  description: >-
+    Retrieve the details of a specific Action by its unique identifier.
+
+    Actions represent state transitions and comments on reviewable resources
+    such as preprints, registrations, node requests, schema responses, and
+    collection submissions.
+
+    An Action includes information about who performed the action (creator),
+    the state change it caused (from_state to to_state), the trigger used to initiate
+    the action, and any optional comment. The action may also include links to
+    related resources, such as the target and the provider.
+
+    #### Returns
+
+    A JSON object with a `data` key containing the full representation of the action.
+
+    #### Permissions
+
+    - You must have at least read permissions on the resource the action applies to.
+    - Only authorized users can view non-public actions (`visible: false`).
+
+    #### Errors
+
+    If the request is unsuccessful, an `errors` key will be returned. Refer to the
+    [Errors and Error Codes documentation](#tag/Errors-and-Error-Codes) for more information.
+
+  tags:
+    - Actions
+  operationId: action_detail_read
+  parameters:
+    - in: path
+      name: action_id
+      type: string
+      required: true
+      description: >-
+        The unique identifier of the action to retrieve.
+
+        Example: `abc123`
+  responses:
+    '200':
+      description: Action retrieved successfully.
+      examples:
+        application/json:
+          data:
+            id: abc123
+            type: review-actions
+            attributes:
+              trigger: accept
+              comment: "The submission was approved by the moderator."
+              from_state: pending
+              to_state: accepted
+              date_created: '2024-01-01T00:00:00Z'
+              date_modified: '2024-01-01T01:00:00Z'
+              auto: false
+              visible: true
+            relationships:
+              creator:
+                links:
+                  related:
+                    href: 'https://api.osf.io/v2/users/user456/'
+                    meta: {}
+                data:
+                  id: user456
+                  type: users
+              target:
+                links:
+                  related:
+                    href: 'https://api.osf.io/v2/preprints/preprint789/'
+                    meta: {}
+                data:
+                  id: preprint789
+                  type: preprints
+              provider:
+                links:
+                  related:
+                    href: 'https://api.osf.io/v2/providers/osf/'
+                    meta: {}
+                data:
+                  id: osf
+                  type: providers
+            links:
+              self: 'https://api.osf.io/v2/actions/abc123/'
+    '403':
+      description: >-
+        Permission denied.
+
+        You do not have permission to view this action. Only users with the
+        appropriate permissions on the resource or provider can view actions.
+    '404':
+      description: >-
+        Action not found.
+
+        The specified action ID does not exist or is not accessible. Ensure you
+        have the correct ID and necessary permissions.

swagger-spec/actions/definition.yaml

@@ -0,0 +1,183 @@
+type: object
+required:
+  - id
+  - type
+  - attributes
+  - relationships
+properties:
+  id:
+    type: string
+    description: The unique identifier of the action.
+    example: abc123
+
+  type:
+    type: string
+    description: The type of action resource.
+    enum:
+      - review-actions
+      - node-request-actions
+      - preprint-request-actions
+      - registration-actions
+      - schema-response-actions
+      - collection-submission-actions
+    example: review-actions
+
+  attributes:
+    type: object
+    required:
+      - trigger
+      - from_state
+      - to_state
+      - date_created
+      - date_modified
+    properties:
+      trigger:
+        type: string
+        description: >
+          The trigger that initiated the action.
+          Triggers correspond to state changes in the workflow and may include submit, accept, reject, withdraw, etc.
+        example: accept
+
+      comment:
+        type: string
+        description: >
+          Optional comment explaining the rationale for the action or providing additional details.
+        example: This submission looks good to me.
+
+      from_state:
+        type: string
+        description: >
+          The state of the resource before the action was performed.
+          This reflects the resource's state prior to the trigger being executed.
+        example: pending
+
+      to_state:
+        type: string
+        description: >
+          The state of the resource after the action was performed.
+          This reflects the resource's updated state as a result of the trigger.
+        example: accepted
+
+      date_created:
+        type: string
+        format: date-time
+        description: The date and time when the action was created.
+        example: '2024-01-01T00:00:00Z'
+
+      date_modified:
+        type: string
+        format: date-time
+        description: The date and time when the action was last modified.
+        example: '2024-01-01T01:00:00Z'
+
+      auto:
+        type: boolean
+        description: >
+          Indicates whether the action was automatically generated by the system (true)
+          or manually triggered by a user (false).
+        example: false
+
+      visible:
+        type: boolean
+        description: >
+          Indicates whether the action is visible to non-admin users (true)
+          or only visible to admins and moderators (false).
+          Visibility typically depends on the provider's review workflow and moderation settings.
+        example: true
+
+  relationships:
+    type: object
+    required:
+      - creator
+      - target
+    properties:
+      creator:
+        type: object
+        description: The user who performed the action.
+        properties:
+          links:
+            type: object
+            properties:
+              related:
+                type: object
+                properties:
+                  href:
+                    type: string
+                    format: uri
+                    example: 'https://api.osf.io/v2/users/user456/'
+                  meta:
+                    type: object
+                    example: {}
+          data:
+            type: object
+            properties:
+              id:
+                type: string
+                example: user456
+              type:
+                type: string
+                example: users
+
+      target:
+        type: object
+        description: The resource (preprint, registration, node request, etc.) on which the action was performed.
+        properties:
+          links:
+            type: object
+            properties:
+              related:
+                type: object
+                properties:
+                  href:
+                    type: string
+                    format: uri
+                    example: 'https://api.osf.io/v2/preprints/preprint789/'
+                  meta:
+                    type: object
+                    example: {}
+          data:
+            type: object
+            properties:
+              id:
+                type: string
+                example: preprint789
+              type:
+                type: string
+                example: preprints
+
+      provider:
+        type: object
+        description: >
+          The provider responsible for managing the review or moderation workflow for the target resource.
+        properties:
+          links:
+            type: object
+            properties:
+              related:
+                type: object
+                properties:
+                  href:
+                    type: string
+                    format: uri
+                    example: 'https://api.osf.io/v2/providers/osf/'
+                  meta:
+                    type: object
+                    example: {}
+          data:
+            type: object
+            properties:
+              id:
+                type: string
+                example: osf
+              type:
+                type: string
+                example: providers
+
+  links:
+    type: object
+    properties:
+      self:
+        type: string
+        format: uri
+        description: The canonical API endpoint for this action.
+        example: 'https://api.osf.io/v2/actions/abc123/'