Bug 55019 - [UDM REST API] enhance moving of objects without subordinates
[UDM REST API] enhance moving of objects without subordinates
Status: VERIFIED FIXED
Product: UCS
Classification: Unclassified
Component: UDM - REST API
UCS 5.0
Other Linux
: P5 normal with 2 votes (vote)
: UCS 5.1
Assigned To: Florian Best
Juan Carlos
https://help.univention.com/t/using-r...
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2022-07-22 09:07 CEST by Florian Best
Modified: 2024-03-08 10:35 CET (History)
4 users (show)

See Also:
What kind of report is it?: Development Internal
What type of bug is this?: ---
Who will be affected by this bug?: ---
How will those affected feel about the bug?: ---
User Pain:
Enterprise Customer affected?:
School Customer affected?:
ISV affected?:
Waiting Support:
Flags outvoted (downgraded) after PO Review:
Ticket number:
Bug group (optional): External feedback
Max CVSS v3 score:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Florian Best univentionstaff 2022-07-22 09:07:16 CEST
Currently we don't differentiate between which objects we are moving in the UDM REST API (and UDM UMC module).

The current way of moving an object is:
PUT the object with different "position". The request is answered with a HTTP 202 Accepted response. The response contains a Location header with a temporary URL which tells the current progress of the move. This again responses with a 3XX redirection to the same URL with a Retry-After header which specifies the time to wait between following the redirect. If the operation is finished on server side a redirection to the moved object in the new location happens.

We need this asynchronous operation as moving objects like CN or OU with subordinates (e.g. 1000 users) may take longer than e.g. the HTTP request timeout.

But we could improve this for objects where we know that they don't have subordinates: Move the object directly in a thread and respond immediately after the move.
Comment 2 Daniel Tröder univentionstaff 2023-09-12 08:30:32 CEST
Clients still have to handle two possible positive responses (200 and 202→30x) to PATCH/PUT requests.

Please elaborate: What will be improved for whom by this change?
Comment 3 Florian Best univentionstaff 2023-09-12 10:20:26 CEST
(In reply to Daniel Tröder from comment #2)
> Clients still have to handle two possible positive responses (200 and
> 202→30x) to PATCH/PUT requests.
> 
> Please elaborate: What will be improved for whom by this change?

But most move cases (like moving users, groups or computers, which are expected to happen in a short time) would not need the progress-mechanism anymore, so that for those things only a simple client which doesn't need to follow multiple redirections is necessary. For containers this would still be the case, yes.

This was especially requested by a customer in the forum: https://help.univention.com/t/using-rest-api-to-move-user-to-different-ou/20194/4
Comment 4 M. Breidt 2023-09-12 10:59:38 CEST
With the proposed change, it will be much easier to use the REST API for a simple move of a single user to a different OU (where the operation is very fast and HTTP timeout is not an issue).

Right now, it requires several requests and sleep delays, all of which makes it a lot more cumbersome (and error-prone) to do this operation:

What is needed right now to move a user object:

1. Send Move request --> Response: 202 with new URL

2. Repeatedly poll new URL to see whether the operation has completed --> Response: 3XX to same URL with Retry-After

3. On completion, the response is a redirection to the moved object.


What would be needed after the change to move a user object:

1. Send Move request --> Response: 200 with new redirection to the moved object
Comment 5 Daniel Tröder univentionstaff 2023-09-12 12:32:49 CEST
OK, so the improvement is: "Simplification of protocol for clients that only want to move leaf nodes."

The precondition is here IMHO, that those clients must be aware of the difference between moving a leaf node and an inner/branch node.

As there is no way to express this technically, that means that the manual should get an update. It should explain the API's behavior in those two different situations.

I see further consequences:

* It makes the protocol slightly more complex for clients that want to support moving both leaf nodes and inner nodes (very little though).

* This is an API change. How should it be handled?

* If we / someone ever decide to make the leaf node (e.g. a user object) into a parent node (with e.g. a contact object as the child node), then the client will fail, because suddenly for the same object instead of '200' the '202→30x' will be returned.
Comment 6 Florian Best univentionstaff 2023-10-18 15:05:09 CEST
(In reply to Daniel Tröder from comment #5)
> OK, so the improvement is: "Simplification of protocol for clients that only
> want to move leaf nodes."
yes

> The precondition is here IMHO, that those clients must be aware of the
> difference between moving a leaf node and an inner/branch node.
well, clients don't need to be aware. They are expected to just follow redirections if there are any, if not then they get a direct success status.

> As there is no way to express this technically, that means that the manual
> should get an update. It should explain the API's behavior in those two
> different situations.
Yes, ok.

> I see further consequences:
> 
> * It makes the protocol slightly more complex for clients that want to
> support moving both leaf nodes and inner nodes (very little though).
No, it doesn't. Either you get a redirection or not but instead the direct result.

> * This is an API change. How should it be handled?
The contract is that we can make API canges in UCS major/minor releases, so this is set to UCS 5.2.
It's also a backwards compatible change, because clients just don't see the redirection anymore but the direct response.

> * If we / someone ever decide to make the leaf node (e.g. a user object)
> into a parent node (with e.g. a contact object as the child node), then the
> client will fail, because suddenly for the same object instead of '200' the
> '202→30x' will be returned.
Yes. For users/user this is unlikely. But in general yes, clients should be designed to expect valid HTTP responses like redirections or 201 accepted and handle it accordingly.
Comment 7 Daniel Tröder univentionstaff 2023-10-18 17:31:20 CEST
Thanks - I'm fine with this change for UCS 5.2.
I should reduce overhead, and if the documentation mentions that clients must handle both 20x and 30x responses, then neither past nor future clients should break.
Comment 8 Juan Carlos univentionstaff 2024-01-15 11:12:16 CET
QA:

Code: OK
Changelog: OK
Both clients work: OK
Tests: OK
Comment 9 Florian Best univentionstaff 2024-03-08 10:35:26 CET
univention-directory-manager-rest (11.0.6)
dd0aefa2786e | feat(udm-rest)!: enhance moving of objects without sub-objects