Bug 54350 - Developer documentation for UDM REST API totally misleading - frustrating experience
Developer documentation for UDM REST API totally misleading - frustrating exp...
Status: NEW
Product: UCS extended documentation
Classification: Unclassified
Component: Developer documentation
unspecified
Other Linux
: P5 normal (vote)
: ---
Assigned To: Docu maintainers
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2022-01-18 10:03 CET by Arvid Requate
Modified: 2022-01-18 11:30 CET (History)
1 user (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):
Max CVSS v3 score:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Arvid Requate univentionstaff 2022-01-18 10:03:25 CET
https://docs.software-univention.de/developer-reference-5.0.html#udm:rest_api

starts with

"6.8. UDM REST API
UCS provides a REST API which can be used to inspect, modify, create and delete UDM objects via HTTP requests.

The API is accessible from https://FQHN/univention/udm/."

But this gave zero success in my experience.

Chat reply from the core developer:

A: "You're on the HTML view - you won't really be able to use that - that's for UMC (once we switch to that). Those are two independent forms you see there. We have a create wizard where you normally select container, template, etc before you get to the actual create page."

Q: "Ok, so how do I use it so that I can create a user with it?"

A: "The HTML view is not meant to create anything - that is only meant for machines to create a UMC representation from it in the end via Javascript."

The documentation continues in 6.8.2. API overview with the statement:

"By visiting https://<SERVERNAME-OR-IP>/univention/udm/ with a browser you can navigate and use the API interactively."

Apparently this is not true. We should write developer documentation that at least *we* can use.
Comment 1 Florian Best univentionstaff 2022-01-18 11:30:29 CET
we should mention that that raw HTML view can be used for interactively looking at the JSON representations in live but that the forms are not meant to be used/working.
We should also link to /univention/udm/schema/ which is the OpenAPI schema UI.