Marmelator/persistence-service
1
0
Fork 0
Code Issues Pull Requests 17 Actions Packages Projects Releases 1.1k Wiki Activity

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

Browse Source
This commit is contained in:
Kresnadi Budisantoso 2024-05-24 11:29:19 +02:00
parent d82935d4a5
commit d516239c0f
2 changed files with 393 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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

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

@ -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