With the beta release of the REST API for the Univention Directory Manager (UDM), a preliminary version of the future standard interface for the integration of applications with the Univention directory service is available. In the following, I would like to give you a brief overview of the objectives and use cases regarding the current status of the API and encourage you to test it – we look forward to your feedback for further improvements for the final version!
What is the „UDM REST API“?
A “REST API” (also called “RESTful API”) is a web service that allows integration between applications.
The REST API of the Univention Directory Manager provides access to all contents of the Univention Corporate Server (UCS) directory service. Its functionality is therefore comparable to that of the already available and further existing scripting interfaces (e.g. the “udm” command line tool). In contrast to these, however, the API is accessible via the web through HTTPS and can be more easily integrated into existing applications using standardized data formats (JSON).
Who is supposed to use the “UDM REST API”?
Univention Directory Manager allows access to the content of the directory service while ensuring that the contents remain consistent and standard compliant. In UCS, therefore, any changes to the directory service are performed using UDM only.
With the REST API, this interface can now be more easily accessed by other systems or other software. We would especially like to facilitate the integration for the following scenarios:
Operators of UCS environments: Integration with existing systems
Use cases include the maintenance of user properties using information from human ressources (HR) systems or the comparison of computer objects with inventory solutions. Operators of an IT infrastructure benefit from using the REST API, as they have direct reading and writing access to UDM from the systems that are to be integrated.
Providers of apps in the Univention App Center: Integration of apps
Manufacturers of software solutions in the Univention App Center can access the directory service in a standardized way via the UDM REST API. The developers of the respective solution benefit from the standardized data models supported by many programming languages as well as from access via HTTPS. Implementations can take place directly in their familiar programming language, since there is no longer any dependency on the UDM Python interfaces.
Use cases include the query of information about the logged-on user or the maintenance of directory service contents that are derived from individual applications.
Simplifications within UCS product development:
For the future development of UCS we plan to increasingly rely on the REST API instead of the Python libraries which have previously been rolled out on every system. With this, we anticipate a reduction of risks by using different library versions in UCS environments, as well as simplifications in the integration with software of different programming languages.
How do I test the UDM REST API??
The REST API is intended for installation on the DC Master or a DC Backup of the UCS domain. For the beta release, it is needed to activate the “unmaintained” repository. After updating to UCS 4.4-0 Errata 168 the package “univention-management-module-udm” can be installed and the service of the same name can be restarted:
ucr set repository/online/unmaintained=yes
service univention-management-module-udm restart
Afterwards the REST API can be accessed under the following URLs:
- API with an interactive webinterface:
https://<FQDN des Servers>/univention/udm/
- Simplified API access and interactive examples via Swagger: https://en.wikipedia.org/wiki/Swagger_(software) :
https://<FQDN des Servers>/univention/udm/schema/
For authentication at the REST API all LDAP accounts can be used, the possibilities here also depend on the LDAP ACLs. The members of the group “Domain Admins” have full access to all properties of the objects in the directory service. The following screenshot shows an example request for retrieving the user object of the administrator account from the interactive documentation via “Swagger”:
the administrator account from the interactive documentation via “Swagger”:
The structure of the URLs is based on the structure of the UDM modules. In the example shown above, the “users/user” module for managing users is part of the URL. To identify a single LDAP object, in our example the DN is placed at the end of the URL. Alternatively, you can also use the attribute
entryUUID (the URL then is „
/univention/udm/object/<entryUUID>/“). The latter URL offers the advantage that it remains unchanged over the entire lifetime of an object. If no DN is specified, objects can either be searched for (“GET”) or new objects can be created (“POST”). You can find further examples and details of the JSON data structures in the interactive documentation.
What will happen until the final version of the REST API arrives?
For the next step we would really appreciate your feedback on the pre-release version. What do you like? What else can we improve? Are there any use cases that cannot yet be covered with the API?
Based on this feedback, we will decide if we will make any further changes to the API and what enhancements are necessary for a final version. Our goal is to release a final version of the REST API within the third quarter of 2019 and activate it on all UCS DC Master and DC Backup. This means that we rely on your feedback: Feel free to comment here in the blog. If you have more specific questions or would like help with testing, please open a topic in our forum (https://help.univention.com/ ).