The introduction to using the REST API is documented for the target group "software developers". The documentation includes access to the REST API (URL + authentication) and some application examples (create, search, edit, delete users; list available modules). The REST API is mentioned in the product documentation, the actual documentation takes place in the developer manual.
Please add a section about auto-generating clients using the produced OpenAPI schema. A good generator I found is https://github.com/OpenAPITools/openapi-generator Being a java program it's fairly easy to use from Windows, MacOS or Linux: $ git clone https://github.com/openapitools/openapi-generator $ cd openapi-generator $ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \ -i http://FQDN/univention/udm/openapi.json \ -g php \ -o /tmp/php_api_client or ... \ -g python \ -o /tmp/python_api_client or ... \ -g PowerShell \ -o /tmp/PowerShell_api_client etc. Then: $ less README.md # <-- language specific readme file
The documentation is in branch jkeiser/4.4-1/udm_rest_doc. Latest version can be found here http://jenkins.knut.univention.de:8080/view/Doku/job/BuildDocBookBranch/164/artifact/webroot/developer-reference-4.4.html Comment #1 is not yet included.
All acceptance criteria are implemented. (https://taiga.knut.univention.de/project/oschwieg-ucs-core/us/97?milestone=20) If Comment #1 is still needed please open a new bug. Resolving this bug for now. If no further changes have to be done please reopen for the branch to be merged.
The PATCH verb is missing.
(In reply to Johannes Keiser from comment #3) > If Comment #1 is still needed please open a new bug. I created Bug #50179.
Looks good to me. The documentation gives a quick overview on how to get started with the api -> OK The examples work -> OK Jenkins branch build is green -> OK Reopen: please merge :)
(In reply to Jürn Brodersen from comment #6) > Reopen: please merge :) I think the documentation should be written in passive, not active. "You" is active writing. E.g: "You can interact with the API by " "By ... can be interacted with the API."
Maybe a introduction can be added, which adds information about the Hypertext Application Language (application/hal+json) media type, which is used: https://tools.ietf.org/html/draft-kelly-json-hal-08 Each resource adds links and/or embedded resources, which can be used to traverse through the API.
Added paragraph for HAL Merged to 4.4-2 9cae67ab78 Bug #50165: reference to developer doc 62f00b68ef Bug #50165: add base doc for udm rest api to developer doc
Improovements for the wording: In the german version I suggest to use the word "Schnittstelle" instead of API (or "Schnittstelle (API)") in the general UCS documentation. Can you also consider Comment #7?
Is the package name relevant in the documentation? The package is installed by default in UCS 4.2-2. So maybe that doesn't matter.
The term "HTTP verbs" is wrong, the correct name is "HTTP methods".
"ETag" could be introduced once as "entity tag (ETag)".
(In reply to Florian Best from comment #13) > "ETag" could be introduced once as "entity tag (ETag)". (In reply to Florian Best from comment #12) > The term "HTTP verbs" is wrong, the correct name is "HTTP methods". (In reply to Florian Best from comment #11) > Is the package name relevant in the documentation? The package is installed > by default in UCS 4.2-2. So maybe that doesn't matter. (In reply to Florian Best from comment #10) > Improovements for the wording: > In the german version I suggest to use the word "Schnittstelle" instead of > API (or "Schnittstelle (API)") in the general UCS documentation. > > Can you also consider Comment #7? 78247aaf2e Bug #50165: spelling c90d71d994 Bug #50165: QA feedback (In reply to Florian Best from comment #7) > I think the documentation should be written in passive, not active. "You" is > active writing. > E.g: > "You can interact with the API by " > "By ... can be interacted with the API." As other parts of the developer doc are also written in this style this is ignored for now. Please open a new bug if necessary.
[4.4-2 5a4fbfe384] Bug #50165: fix typo pdf -> OK html -> OK -> Verified
UCS 4.4-2 has been released.