General
Optional properties are marked with a question mark (?) at the end of the type. Instead of returning a property as
null, it can also simply be omitted.
Endpoints
Flow fetches each entity with a GET request to the external system's API, relative to the configured Base URL. Each
endpoint returns an array of the corresponding entity (see Import Entities).
| entity | endpoint |
|---|---|
| Users | GET {baseUrl}/users |
| Organizations | GET {baseUrl}/organizations |
| Courses | GET {baseUrl}/courses?semesterId={semesterId} |
| Surveys | GET {baseUrl}/surveys |
Student data is embedded in the user, and groups, events and student registrations are nested inside their course, so
there are no separate student, group or event endpoints. All endpoints return JSON (application/json).
The surveys endpoint is only required when enableSurvey is enabled in the System Configuration. Otherwise it does
not have to be implemented, or it can simply return an empty array.
Authentication
Flow sends the configured API secret with every request in the Authorization header:
Authorization: Bearer TODO_REPLACE_WITH_API_SECRET
The API must require and validate this header and reject unauthorized requests with 401 Unauthorized.
Entity import order
Flow fetches and imports the entities in the following order, so that all references (e.g. a course's lecturers and registered students, a course's organization) can be resolved:
- Users
- Organizations
- Courses (including their groups and events)
- Surveys
Global integrity check
After all entities have been imported, an integrity check runs to verify that all references can be resolved. Inconsistent data is reported as warnings in the import log without failing the import (see Import Log).
Date Time format (Date data type)
The ISO 8601 format yyyy-MM-dd'T'HH:mm:ss.SSSX is used, such as 2023-03-10T12:30:00.000+01 or
2023-03-10T11:30:00.000Z.