Univention Bugzilla – Bug 55019
[UDM REST API] enhance moving of objects without subordinates
Last modified: 2024-03-08 10:35:26 CET
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.
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?
(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
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
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.
(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.
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.
QA: Code: OK Changelog: OK Both clients work: OK Tests: OK
univention-directory-manager-rest (11.0.6) dd0aefa2786e | feat(udm-rest)!: enhance moving of objects without sub-objects