Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MNT-24127] Added Endpoint To Calculate Folder Size #213

Merged
merged 7 commits into from
Jun 24, 2024
133 changes: 125 additions & 8 deletions src/main/webapp/definitions/alfresco-core.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -123,12 +123,19 @@ parameters:
description: The identifier of a target node.
required: true
type: string
nodeFolderIdParam:
name: nodeId
in: path
description: The identifier of a folder node.
required: true
type: string
maxItemsForSizeParam:
name: maxItems
in: query
description: |
This assists in handling scenarios where ***large files*** or ***subfolders*** exist within a folder,
allowing the folder size determination mechanism to function in chunks.

So that calculating the huge folder will be done efficiently.
If not supplied then the default value is 100.
required: false
type: integer
minimum: 1
default: 100
nodeMinimalEntryIncludeParam:
name: include
in: query
Expand Down Expand Up @@ -2484,7 +2491,96 @@ paths:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/nodes/{nodeId}/calculateSize':
post:
tags:
- nodes
summary: Calculate a folder size
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we supporting the API to calculate the size of a file. If yes, then we shd mention in the description.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are only calculating the size of a folder not file.

description: |

This may be executed against a node specified by **nodeId** and this nodeId must be a valid node ID.
Furthermore, this POST endpoint will be executed **asynchronously** with a `202` HTTP response signifying that
the request has been accepted successfully.

The response body will include the ```nodeId``` of the pending action, which can be used in a
**GET/calculateSize** endpoint to check if the action's status has been completed, at which point the result will be returned, comprising ```the size of the node in bytes```.

Essentially, ```maxItems``` ***parameter*** is utilized for pagination purposes.

By default, **results are limited to the first 100.**
Results can be restricted using "paging". For example:

```JSON
"paging": {
"maxItems": "50",
"skipCount": "28"
}
```
This assists in handling scenarios where large files or subfolders exist within a folder, allowing the folder size determination mechanism to function in chunks.

operationId: calculateSize
produces:
- application/json
parameters:
- $ref: '#/parameters/nodeTargetIdParam'
- $ref: '#/parameters/maxItemsForSizeParam'
responses:
'202':
description: Request Accepted
schema:
$ref: '#/definitions/sizeAcknowledgedResponse'
'400':
description: |
Invalid parameter: **nodeId** is not of Folder Type
'401':
description: Authentication failed
'403':
description: Current user does not have permission for **nodeId**
'404':
description: Entity with **nodeId** does not exist
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
Copy link
Contributor

@suneet-gupta suneet-gupta Jun 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What error code are we returning in case its a valid node id but this is a retention-schedule node id i.e. invalid node type

Copy link
Contributor Author

@mohit-singh4 mohit-singh4 Jun 21, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are returning 404- nodeId does not exist, as we are only considering folder type node.

Copy link
Contributor

@suneet-gupta suneet-gupta Jun 21, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But here node id exist in the system but it has different node type. I think we should have a different message and may be status code as well. Please check other endpoints.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with 400 status code. with description

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Plz once validate the message with other endpoints in the swagger so that we are having similar standards. Rest looks good to me.

get:
tags:
- nodes
summary: Get the size of folder after initiating POST/calculateSize Endpoint.
description: |
***Receiving the size***

This endpoint takes ```nodeId``` as a path parameter and returns the result after executing above POST request.

Below are the three stages, which reflect the status for the present execution ***nodeId***.

```
NOT INITIATED: Not Iniated yet.
IN-PROGRESS: Calculating execution is in progress.
COMPLETED: Calculation has been done.
```
operationId: getSize
produces:
- application/json
parameters:
- $ref: '#/parameters/nodeTargetIdParam'
responses:
'200':
description: Successful Response
schema:
$ref: '#/definitions/calculateSizeResponse'
'400':
description: |
Invalid parameter: **nodeId** is not of Folder Type
'401':
description: Authentication failed
'403':
description: Current user does not have permission for **nodeId**
'404':
description: Entity with **nodeId** does not exist
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/nodes/{nodeId}/secondary-children':
post:
x-alfresco-since: "5.2"
Expand Down Expand Up @@ -4434,7 +4530,7 @@ paths:
**nodeId** does not exist
'412':
description: |
Content is archived and is inaccessible
Content is archived and is inaccessible
'501':
description: The actual ContentStore implementation can't fulfil this request
default:
Expand Down Expand Up @@ -8582,7 +8678,7 @@ paths:
parameters:
- $ref: '#/parameters/auditApplicationIdParam'
- $ref: '#/parameters/skipCountParam'
- $ref: '#/parameters/omitTotalItemsParam'
- $ref: '#/parameters/omitTotalItemsParam'
- $ref: '#/parameters/orderByParam'
- $ref: '#/parameters/maxItemsParam'
- name: where
Expand Down Expand Up @@ -10690,6 +10786,27 @@ definitions:
$ref: '#/definitions/PermissionsInfo'
definition:
$ref: '#/definitions/Definition'
calculateSizeResponse:
type: object
properties:
id:
type: string
description: Provides the id for which POST/calculateSize has been initiated.
size:
type: string
description: Provides a folder size in bytes.
calculatedAtTime:
type: string
description: Provides the time when the calculating folder size will be completed.
status:
type: string
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a good practice to add description for all the fields.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

Copy link
Contributor

@suneet-gupta suneet-gupta Jun 21, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should have "number of files" field in the response. This was earlier part of RFC confluence page as well and is in sync with the requirement from Product Manager.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the same.
Done

description: Provides a status that signifies the completion of the calculateSize mechanism.
sizeAcknowledgedResponse:
type: object
properties:
executionId:
type: string
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above. Add the desctiption for the field.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

description: Provides nodeId indicating that the request has been acknowledged.
ProbeEntry:
type: object
required:
Expand Down
Loading