Bulk metadata sharing API

[vietnguyen]

Requirement

• This issue is about supporting "bulk sharing" of metadata objects. This means the ability to add or remove many users and user groups to many objects in one API operation.
• This API should not support keeping metadata objects in sync over time, and instead treat it as a one-time operation.
• The API needs to respect the sharing access control, in that the current user must have access to edit the sharing of the objects being updated.
• The main use-case for this API is a web client (maintenance app) which will add or remove user/user groups to/from many metadata objects in bulk.

Endpoint

• Add new /batch endpoint to all metadata api.
• Send PATCH request to this new endpoint ( with header Content-type: application/json-patch+json ? )

  /api/dataElements/batch

Parameters

Name	Default	Description
atomic	true	If this is set to true, then the batch function will stop and not updating any objects if there is an error. Otherwise, if this is false then the function will try to proceed with best effort mode.

Backend function

• Add new batch method to AbstractCrudController for serving api/{object-type}/batch
• Create a new class JsonIdPatchOperation which extends JsonPatchOperation and add an id property.
• Get list of JsonIdPatchOperation from request.getInputStream().
• Get persisted objects using id property from List<JsonIdPatchOperation>.
• Apply List<JsonIdPatchOperation> to persisted objects .
• Import patched objects using metadata import service.

Validation

• All object UID will be validated for existence.
• Current User need to have METADATA_WRITE permission on updating objects.
• All existing validations from metadata import service.

Response

• Response format should be same as from /api/metadata api.

Payload

[
    {
        "id": "fbfJHSPpUQD",
        "op": "replace",
        "path": "/sharing/users",
        "value": {
            "NOOF56dveaZ": {
                "access": "rw------",
                "id": "NOOF56dveaZ"
            },
            "Kh68cDMwZsg": {
                "access": "rw------",
                "id": "Kh68cDMwZsg"
            }
        }
    },
    {
        "id":"fbfJHAJpUQS",
        "op": "add",
        "path": "/sharing/users/NOOF56dveaZ",
        "value": {
            "access": "rw------",
            "id": "NOOF56dveaZ"
        }
    },
    {
        "id": "cYeuwXTCPkU",
        "op": "remove",
        "path": "/sharing/users/N3PZBUlN8vq"
    },
    {
        "id": "GOLswS44mh8",
        "op": "add",
        "path": "/sharing/userGroups",
        "value": {
            "NOOF56dveaZ": {
                "access": "rw------",
                "id": "NOOF56dveaZ"
            },
            "Kh68cDMwZsg": {
                "access": "rw------",
                "id": "Kh68cDMwZsg"
            }
        }
    }
]

Bonus

• Can be applied to other properties as well ?

[larshelge]

Wonder if the naming (/dataElements/batch) could be made a bit more descriptive and specific, i.e. batch is quite generic. Perhaps instead use /dataElements/sharing. That way it is consistent with dataElements/{uid}/sharing, and being at dataElements level implies it applies to many objects.

[jbee]

We said we make it a https://github.com/dhis2/notes/discussions right? Does it exist? Can we link it here?

[vietnguyen]

moved here https://github.com/dhis2/notes/discussions/317