Overview

The UCS@school Kelvin REST API provides HTTP endpoints to create and manage UCS@school domain objects like school users, school classes, schools (OUs) and computer rooms.

The same objects can be managed through a graphical web interface (UMC modules) and a Python API.

The components participating in the UCS@school Kelvin REST API are:

• clients of the UCS@school Kelvin REST API (for example the Python client)

• the UCS@school Kelvin REST API server on the DC master / DC backup [1]

• the Open Policy Agent used for authorization

• the UDM REST API client component of the UCS@school Kelvin REST API

• the UDM REST API server on the DC master

• the LDAP server on the DC master

Components

To be more precise, let’s take a look at the topology picture, starting with the client:

1. Clients are HTTP clients sending requests to https://<fqdn>/ucsschool/kelvin/v1/<resource>/ or https://<fqdn>/ucsschool/kelvin/v2/<resource>/ with <fqdn> being the address of the DC master and <resource> being the object type (users, classes etc) to manage. The v2 endpoints use the same protocol as v1. When reading or searching for objects, however, v2 does not support hooks.

2. The UCS@school Kelvin REST API can only be accessed through HTTPS on the DC master or DC backup after installing an app (see installation and configuration instructions). The web server Apache runs a reverse proxy for the URL path /ucsschool/kelvin/. All access to that path is forwarded to the UCS@school Kelvin REST API server running inside a Docker container.

3. To manage the UCS@school resources, a token must first be retrieved at https://<fqdn>/ucsschool/kelvin/token/. The server will access the OpenLDAP server directly to authenticate and authorize the connecting client. If both succeed, a temporary token is issued to the client.

4. When the client requests a resource (including a valid token in the transmission), the UCS@school Kelvin REST API server will use its UDM REST API client component to access the UDM REST API on the DC master.

5. The UDM REST API will then query the OpenLDAP server to retrieve the required information or make the requested changes.

Version 2 architecture

Added in version 4.0.0.

Important

The version 2 API is a preview and not intended for production use. Version 1 remains the stable, maintained, and recommended API for production.

The version 1 API described above reads every request live from LDAP through the UDM REST API. The version 2 API works differently: read and search requests (GET, HEAD) are served from a PostgreSQL-backed cache instead of querying LDAP directly. This improves performance for read-heavy workloads, at the cost of new infrastructure and eventual consistency. Write requests (POST, PUT, PATCH, DELETE) still go through the UDM REST API just like in version 1.

Two additional components participate in the version 2 API:

• the Kelvin DB, a PostgreSQL database, which stores schools, groups, and users (see Database settings)

• the Kelvin connector, which subscribes to the Provisioning Service and mirrors changes into that database (see Provisioning subscription)

Note

The Kelvin connector runs only on the Primary Directory Node. Consequently, for the version 2 API to work on a Backup Directory Node, Kelvin must also be installed on the Primary Directory Node.

Eventual consistency: because reads are served from the Kelvin DB and writes go through UDM, reads in version 2 are eventually consistent. After a write it can take a moment (usually in the range of 1 to 2 seconds) for the cache to reflect the change.

Footnotes

[1]

The app UCS@school Kelvin REST API can be installed on both DC master and DC backup. The rest of the text will talk only about DC master, but the same is valid for DC backup.