Added download endpoints to DocuMine spec to make the DocuMine API a superset of the RedactManager API.

persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml

@@ -10,7 +10,7 @@ info:
     Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`.
 
     Please also note that the `authorizationUrl` and `tokenUrl` in this specification contain `{workspaceId}` placeholders that
-    must be replaced by your respective RedactManager workspace identifier.
+    must be replaced by your respective DocuMine workspace identifier.
 
     Example Headers:
     ```properties
@@ -39,9 +39,11 @@ tags:
     description: Operations for managing files within a dossier.
   - name: 4. Components
     description: Operations related to components of a file within a dossier.
-  - name: 5. Users
+  - name: 5. Downloads
+    description: Operations related to download packages.
+  - name: 6. Users
     description: Operations related to users.
-  - name: 6. License
+  - name: 7. License
     description: Operations related to license information and usage metrics.
 paths:
   /api/dossier-templates:
@@ -560,6 +562,47 @@ paths:
           $ref: '#/components/responses/429'
         "500":
           $ref: '#/components/responses/500'
+  /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/create-download:
+    post:
+      operationId: prepareDossierDownload
+      tags:
+        - 2. Dossiers
+      summary: Initiate the creation of a download package for all files of a dossier.
+      description: |
+        To download files and reports, a download package needs to be prepared. This endpoint
+        facilitates to define the content of the download package and to start the creation of it for all
+        files of the dossier. The response of this endpoint contains an identifier for the download that
+        is needed to query the status until the download package is prepared, and finally to actually 
+        download the file once it is available.
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+        - $ref: '#/components/parameters/dossierId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DownloadRequest'
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadStatus'
+          description: |
+            Successfully started the creation of the download package for all files of the requested dossier.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-dossier'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
   /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files:
     get:
       operationId: getDossierStatus
@@ -724,6 +767,48 @@ paths:
           $ref: '#/components/responses/429'
         "500":
           $ref: '#/components/responses/500'
+  /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/{fileId}/create-download:
+    post:
+      operationId: prepareFileDownload
+      tags:
+        - 3. Files
+      summary: Initiate the creation of a download package for a single file of a dossier.
+      description: |
+        To download files and reports, a download package needs to be prepared. This endpoint
+        facilitates to define the content of the download package and to start the creation of it for the
+        file. The response of this endpoint contains an identifier for the download that is needed to
+        query the status until the download package is prepared for download, and finally to actually 
+        download the file once it is available.
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+        - $ref: '#/components/parameters/dossierId'
+        - $ref: '#/components/parameters/fileId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DownloadRequest'
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadStatus'
+          description: |
+            Successfully started the creation of the download package for the requested file.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-file'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
   /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/bulk/delete:
     post:
       operationId: deleteFiles
@@ -764,6 +849,47 @@ paths:
           $ref: '#/components/responses/429'
         "500":
           $ref: '#/components/responses/500'
+  /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/bulk/create-download:
+    post:
+      operationId: prepareBulkDownload
+      tags:
+        - 3. Files
+      summary: Initiate the creation of a download package for specific files within a dossier.
+      description: |
+        To download files and reports, a download package needs to be prepared. This endpoint
+        facilitates to define the content of the download package and to start the creation of it for
+        multiple files of a dossier. The response of this endpoint contains an identifier for the download
+        that is needed to query the status until the download package is prepared for download, and finally
+        to actually download the file once it is available.
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+        - $ref: '#/components/parameters/dossierId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkDownloadRequest'
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadStatus'
+          description: |
+            Successfully started the creation of the download package for the requested files.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-dossier'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
   /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/{fileId}/attributes:
     post:
       operationId: setFileAttributes
@@ -881,11 +1007,131 @@ paths:
           $ref: '#/components/responses/429'
         "500":
           $ref: '#/components/responses/500'
+  /api/download:
+    get:
+      operationId: getDownloadStatusList
+      tags:
+        - 5. Downloads
+      summary: Get the list of downloads for the current user
+      description: |
+        This endpoint facilitates to retrieve the list of downloads for the current user. The response contains 
+        status objects that represent each download and provide information on whether the download is still 
+        in preparation, is already available or whether an error occurred when the download package was created.
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadStatusList'
+          description: List of all downloads of the current users successfully retrieved.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
+  /api/downloads/{downloadId}:
+    get:
+      operationId: getDownloadStatus
+      tags:
+        - 5. Downloads
+      summary: Get the status for a specific download of the current user
+      description: |
+        This endpoint facilitates to retrieve the status for a specific download. In addition to other 
+        information, the status indicates whether the download is still being prepared, is already 
+        available, or whether an error occurred when the download package was created.
+      parameters:
+        - $ref: '#/components/parameters/downloadId'
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadStatus'
+          description: Status of the download successfully retrieved.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-download'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
+    delete:
+      operationId: deleteDownload
+      tags:
+        - 5. Downloads
+      summary: Deletes a specific download.
+      description: |
+        This endpoint facilitates the removal of a download.
+      parameters:
+        - $ref: '#/components/parameters/downloadId'
+      responses:
+        "204":
+          description: |
+            Download deletion successful. This confirms the absence of the specified download, irrespective of its previous existence.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-download'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
+  /api/downloads/{downloadId}/download:
+    get:
+      operationId: download
+      tags:
+        - 5. Downloads
+        - persistence-service
+      summary: Download the download package.
+      description: |
+        This endpoint facilitates to actually download the created download package. The request will
+        only be successful if the status of the download is `READY`.
+      parameters:
+        - $ref: '#/components/parameters/downloadId'
+      responses:
+        "200":
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+                example: attachment; filename*=utf-8''example.zip
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+          description: Successfully downloaded the requested file.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-download'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
   /api/users:
     get:
       operationId: getUsers
       tags:
-        - 5. Users
+        - 6. Users
         - tenant-user-management
       summary: Get a list of users
       description: |
@@ -916,7 +1162,7 @@ paths:
     get:
       operationId: getUserById
       tags:
-        - 5. Users
+        - 6. Users
       summary: Retrieve a specific user by its identifier.
       description: |
         This endpoint facilitates to retrieve a specific user.
@@ -943,7 +1189,7 @@ paths:
     post:
       operationId: getLicenseReport
       tags:
-        - 6. License
+        - 7. License
       summary: Generate and retrieve a license usage report.
       description: |
         This endpoint enables users to create and fetch a report detailing the active usage of licenses. The report contains 
@@ -1302,6 +1548,15 @@ components:
         - `true`: The component object's field `componentDetails` stores detailed information about the *source* of its
           respective value(s).
         - `false` (default): The component object does not contain a field `componentDetails`.
+    downloadId:
+      name: downloadId
+      in: path
+      required: true
+      schema:
+        type: string
+      style: simple
+      explode: false
+      description: The identifier for the file to download.
     username:
       name: username
       in: query
@@ -1636,7 +1891,7 @@ components:
           description: |
             A text that can be added to provide further details about the status. E.g., what it is intended for or 
             the circumstances under which it can be used.
-          example: "Dossiers with this status should only contain approved files and indicate that the users have completed the redactions."
+          example: "Dossiers with this status should only contain approved files and indicate that the users have completed the component extractions."
         rank:
           format: int32
           type: integer
@@ -2935,6 +3190,124 @@ components:
             $ref: '#/components/schemas/RuleValidationMessage'
           type: array
       type: object
+    DownloadStatus:
+      type: object
+      description: Detailed information about a specific download.
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: The unique identifier of the download.
+          example: b5e2cf01-8bb6-4fcd-ad88-0efb611195da
+        userId:
+          type: string
+          format: uuid
+          description: The unique identifier of the user who initiated the download.
+          example: caa8b54a-eb5e-4134-8ae2-a3946a428ec7
+        filename:
+          type: string
+          description: The name of the download file.
+          example: my-component-dossier.zip
+        mimeType:
+          type: string
+          description: The mime type of the download file.
+          example: application/octet-stream
+        errorCause:
+          type: string
+          description: |
+            If the status is `FAILED`, this field contains information about the error that happened
+            while preparing the download package. This information is intended to be included in a 
+            bug report if the error occurs repeatedly and indicates a general problem with DocuMine.
+          example: ""
+        status:
+          type: string
+          enum:
+            - QUEUED
+            - GENERATING
+            - COMPRESSING
+            - READY
+            - FAILED
+          description: |
+            The status of the download file. In particular:
+            - `QUEUED` - The download job has been created and is waiting to be processed by the system.
+            - `GENERATING` - The system currently creates the files for the download package.
+            - `COMPRESSING` - The system creates a ZIP archive that will contain all files of the download package.
+            - `READY` - The download package is ready for download. Please note that the download will be kept only
+              for a certain period. This period can be configured in the settings of your DocuMine workspace.
+            - `FAILED` - An error occurred while preparing the download. The `errorCause` field might contain 
+              additional details on the error.
+          example: READY
+        creationDate:
+          type: string
+          format: date-time
+          description: The date and time when the user initiated the download.
+          example: 2023-03-29T11:41:08.886Z
+        lastDownload:
+          type: string
+          format: date-time
+          description: The date and time when the user last downloaded the file.
+          example: 2023-03-29T13:11:05.123Z
+        fileSize:
+          type: integer
+          format: int64
+          description: The size of the download file in bytes.
+          example: 1654231
+        dossierId:
+          type: string
+          format: uuid
+          description: The identifier of the dossier to which the content of the download package belongs.
+          example: 20354d7a-e4fe-47af-8ff6-187bca92f3f9
+        fileIds:
+          type: array
+          items:
+            type: string
+            description: The list of file identifiers to which the content of the download package belongs.
+          example:
+            - 51d3f70ac322c98dc4db70a2ac44115a
+            - 1fdbd888b39059c8cf171df26f62f8a5
+        downloadFileTypes:
+          $ref: '#/components/schemas/DownloadFileTypes'
+        reportTemplateIds:
+          $ref: '#/components/schemas/ReportTemplateIdList'
+    DownloadStatusList:
+      type: object
+      description: Represents a list detailing the status of multiple downloads.
+      properties:
+        downloadStatus:
+          type: array
+          items:
+            $ref: '#/components/schemas/DownloadStatus'
+          description: Each item contains the status details of a download.
+    DownloadRequest:
+      type: object
+      description: Request payload to initiate the preparation of the download.
+      properties:
+        downloadFileTypes:
+          $ref: '#/components/schemas/DownloadFileTypes'
+        reportTemplateIds:
+          $ref: '#/components/schemas/ReportTemplateIdList'
+        redactionPreviewColor:
+          type: string
+          example: "#9398a0"
+          description: |
+            A hexadecimal color code that is used to define the highlighting color of the redaction annotations in 
+            the `PREVIEW` file.
+            
+            - Black is `#000000`
+            - White is `#ffffff`
+            - Grey is `#cccccc`
+    BulkDownloadRequest:
+      allOf:
+        - $ref: '#/components/schemas/DownloadRequest'
+        - type: object
+          description: Request payload to initiate the preparation of the download of multiple files.
+          properties:
+            fileIds:
+              type: array
+              description: A list with unique identifiers of the files for which the download is to be prepared.
+              items:
+                type: string
+                description: The unique identifier of a file.
     User:
       type: object
       description: Basic information about a user.
@@ -2965,7 +3338,7 @@ components:
           type: array
           description: |
             The roles of the user. In particular:
-            - `USER` - default user permission to work with RedactManager
+            - `USER` - default user permission to work with DocuMine
             - `MANAGER` - additional privileges to create and manage dossiers
             - `USER_ADMIN` - administration privileges limited to manage users only
             - `ADMIN` - general administration privileges

persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml

@@ -39,11 +39,13 @@ tags:
     description: Operations for managing dossiers that are based on a dossier template.
   - name: 3. Files
     description: Operations for managing files within a dossier.
-  - name: 4. Downloads
+  - name: 4. Components
+    description: Operations related to components of a file within a dossier. These endpoints are not available for RedactManager.
+  - name: 5. Downloads
     description: Operations related to download packages.
-  - name: 5. Users
+  - name: 6. Users
     description: Operations related to users.
-  - name: 6. License
+  - name: 7. License
     description: Operations related to license information and usage metrics.
 paths:
   /api/dossier-templates:
@@ -775,7 +777,7 @@ paths:
     get:
       operationId: getDownloadStatusList
       tags:
-        - 4. Downloads
+        - 5. Downloads
       summary: Get the list of downloads for the current user
       description: |
         This endpoint facilitates to retrieve the list of downloads for the current user. The response contains 
@@ -802,7 +804,7 @@ paths:
     get:
       operationId: getDownloadStatus
       tags:
-        - 4. Downloads
+        - 5. Downloads
       summary: Get the status for a specific download of the current user
       description: |
         This endpoint facilitates to retrieve the status for a specific download. In addition to other 
@@ -832,7 +834,7 @@ paths:
     delete:
       operationId: deleteDownload
       tags:
-        - 4. Downloads
+        - 5. Downloads
       summary: Deletes a specific download.
       description: |
         This endpoint facilitates the removal of a download.
@@ -858,7 +860,7 @@ paths:
     get:
       operationId: download
       tags:
-        - 4. Downloads
+        - 5. Downloads
         - persistence-service
       summary: Download the download package.
       description: |
@@ -895,7 +897,7 @@ paths:
     get:
       operationId: getUsers
       tags:
-        - 5. Users
+        - 6. Users
         - tenant-user-management
       summary: Get a list of users
       description: |
@@ -926,7 +928,7 @@ paths:
     get:
       operationId: getUserById
       tags:
-        - 5. Users
+        - 6. Users
       summary: Retrieve a specific user by its identifier.
       description: |
         This endpoint facilitates to retrieve a specific user.
@@ -953,7 +955,7 @@ paths:
     post:
       operationId: getLicenseReport
       tags:
-        - 6. License
+        - 7. License
       summary: Generate and retrieve a license usage report.
       description: |
         This endpoint enables users to create and fetch a report detailing the active usage of licenses. The report contains