Practical Use of the REST API Using the Example of EGroupware

The Univention Directory Manager (UDM) enables access to content in the LDAP directory service, for example viewing, editing, deleting, and moving of objects (users, groups, computers, printers, shares, etc.).
The UDM can be accessed and controlled via both the web interface and the command line. In UCS 4.4-2, a third option has now also been added: the REST API. This interface connects applications with the UCS directory service via HTTPS and supports the maintenance of the user properties or computer objects of the connected systems.
This article begins by explaining the technical background of the REST API and its implementation in UCS.
During the implementation of the REST API, an exciting exchange took place between Univention and the developers at EGroupware GmbH in Kaiserslautern, Germany. As a result, EGroupware became the first solution to employ the new interface in the Univention App Center. In the second section of the article, Ralf Becker from EGroupware explains the implementation of the new API and the advantages it offers providers of third-party applications.

What is a REST API?

REST stands for Representational State Transfer and API for Application Programming Interface. REST defines an architectural style which takes the basic concept of the World Wide Web to heart and describes how distributed services and systems can communicate with each other. The key ideas behind REST are as follows:  • All pieces of information on the web are referred to as resources, e.g., users in UCS.

• Each resource can be accessed or named via a unique URI (Uniform Resource Identifier) (e.g., /Univention/udm/users/user/uid=administrator).
• The current or a desired new state of a resource is defined via representations in the network, e.g., an HTTP message. The representations are explicitly or implicitly marked as either cacheable or not cacheable.
• Representations consist of data in a MIME media format (e.g., text/html, application/hal+json, image/jpeg, or also multipart/form-data) as well as metadata which describe these data (e.g., MIME media type, links, last modification time, control data, caching information, etc.).
• Besides the current state of the resource, representations also contain all the currently available possibilities for interaction.

As such, resources are connected with each other through links and relationship types. For example, if a user were to link to his primary group, the program code would look like this:

<a href="/univention/udm/group/group/cn=Domain+Admins" rel="udm:users/user:primaryGroup">

Possible state changes, for example deletion, editing, and creation, are possible via forms or links to forms. Hypermedia as the Engine of Application State (HATEOAS) is the engine of the applications and contains the logic required for state changes. The communication itself is stateless, meaning that any message can be understood without knowledge of the earlier messages.
No specific, client-side logic or interface definition is required, merely standardized protocols and data formats, since each message describes itself. Possible intermediate layers, such as proxy servers, gateways, or caches, can also understand and expand or change the messages. Optionally, program code such as JavaScript can be supplied to expand the client functionality.

The UDM REST API

The UDM REST interface is a web service developed in Python which supports the asynchronous Tornado framework to provide HTTP resources for the UDM objects. The interface provides the contents of the directory service in the JSON HAL (Hypertext Application Language) foramt. In addition, there is an OpenAPI schematization available for the endpoints. An example of a schema definition for objects of the UDM REST API can be found on our demo instance (user: Administrator, password: univention). Our developer manual explains how to use the interface and what possibilities it offers in detail.
The API is aimed at operators of UCS environments looking to integrate existing systems, for example for the maintenance of user properties using information from HR systems or when comparing computer objects with inventory solutions.
In short: the interface is designed for all those who want read and write access to UDM directly from connected systems.
App providers in the Univention App Center also benefit from the REST API because it allows standardized HTTPS access to the directory service. Since there is no longer a dependency on the UDM Python interface, developers are no longer bound to this programming language and can also integrate the solution in their preferred language. Read on to find out how EGroupware uses the new REST API to connect its own groupware solution to UCS.

EGroupware and the REST API

As already mentioned, EGroupware is the first solution in the Univention App Center to employ the new REST API; earlier versions used UDM. The changeover was effected in the course of the EGroupware app upgrade from Version 17.1 to Version 19.1, and we now want to take a peek behind the scenes.
The EGroupware app is an app which communicates very intensively with the directory service. Unlike some other apps, it doesn’t just accept data but also allows changes to the directory service. Typical EGroupware users/administrators generally manage the users and groups via their own groupware solution and not via UCS – which has already led to complications in the past, particularly with regard to the creation and changing of group and user objects in LDAP.

One Container for Everything

The new EGroupware version also uses Docker Compose, a tool for creating, editing, and running multiple Docker containers. Docker Compose therefore supersedes the UCS AppBox, and the EGroupware Docker container is no longer based on UCS. The container which is now used is not one specially created for UCS. Instead, the REST API allows the use of the same container that EGroupware also uses everywhere else – an enormous advantage, as this container is tested far more extensively than a container used solely for UCS.
This was made possible by the new interface, as the communication between the container and the UCS system is now considerably smoother. It is now possible to create a new user in EGroupware, assign it an initial password, and specify all the settings for Samba and Active Directory at UCS level directly.
Plus, there is another advantage for UCS administrators: the EGroupware container integrates better into the system and can make use of all UCS update mechanisms.

Here’s to a Great Collaboration!

The exchange between EGroupware and Univention employees was fruitful for both parties. As a developer of a groupware solution which is available in the Univention App Center, we value dialog where both sides treat each other as equals and the fact that it is always possible to reach competent contact partners at Univention. The company offers personal contact instead of a hotline or ticket system. As developers at Univention, we are very happy in return for the input we receive from external partners: in EGroupware, a specialized partner tested out the new REST API for us and provided us with valuable feedback on how we can improve the new REST API even further.