API: Unterschied zwischen den Versionen

Aus TraiNexWiki
Wechseln zu:Navigation, Suche
(Letzte funktionale Änderungen)
(Siehe auch)
 
(8 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
  
 
==Allgemein==
 
==Allgemein==
 +
Die API (application programming interface, wörtlich ‚Anwendungs­programmier­schnittstelle‘) ermöglicht es, dass andere Programme lesend (oder ggf. in definierten Ausnahmefällen schreibend) an TraiNex angebunden werden. Diese Schnittstelle zur Programmierung von Anwendungen kann von berechtigten Programmierenden der Hochschule genutzt werden, um Daten in strukturierter Form aus den TraiNex-Datenbanken auszulesen (oder ggf. in definierten Ausnahmefällen zu schreiben). Technische Details zur API werden NICHT hier im Wiki sondern in einem separaten Dokument beschrieben, was nur Kunden ausgehändigt wird.<BR>
  
Die API (application programming interface, wörtlich ‚Anwendungs­programmier­schnittstelle‘) ermöglicht es, dass andere Programme lesend (oder ggf. in definierten Ausnahmefällen schreibend) an TraiNex angebunden werden. Diese Schnittstelle zur Programmierung von Anwendungen kann von berechtigten Programmierenden der Hochschule genutzt werden, um Daten in strukturierter Form aus den TraiNex-Datenbanken auszulesen (oder ggf. in definierten Ausnahmefällen zu schreiben).<BR>
+
<BR>
 +
Folgende API-Aufrufe und Funktionen sind grob möglich<BR>
 +
* Lesen von Stammdaten/Adress-Daten/Semesterangaben
 +
* Lesen von Bewertungen/Noten
 +
* Aktualisieren/Anlegen von Stammdaten
 +
* Voreintragung von Bewertungen/Noten
 +
* Download von vorbereitetem Prüfungstermin-XML
 +
* weitere Funktionen sind in Entwicklung und beschrieben in der separaten Dokumentation
 +
 
 +
== Haftung, Datenschutz, ADV ==
 +
 
 +
Mit der Übergabe der Zugangsdaten für die Schnittstelle, ist es möglich, lesend auf personenbezogene Daten der TraiNex-Nutzer zuzugreifen. Ebenfalls möglich kann es ein, dass Stamm-Daten für Bewerber oder andere Personen oder Noten geschrieben oder verändert oder geleert werden.
 +
 
 +
* Die TraiNings-Online GmbH hat Vorkehrungen getroffen, um einen Missbrauch der Schnittstelle zu verhindern.
 +
* Die TraiNings-Online GmbH übernimmt keinerlei Haftung für eine Ausnutzung der Schnittstelle durch unberechtigte oder berechtigte Dritte.
 +
* Die Vereinbarung zur Auftragsdatenvereinbarung sowie das Verfahrens-Verzeichnis der datenschutzrelevanten Prozesse sind seitens des Kunden (und nicht durch die TraiNings-Online GmbH) anzupassen.  
 +
* Ohne Zustimmung zum Haftungsausschluss kann die Schnittstelle aus haftungsrechtlichen Gründen nicht in Betrieb genommen werden.  
 +
 +
 
 +
== Aktivierung ==
  
 
Die Aktivierung der API erfolgt auf Wunsch durch [[TrOn]] und ist eine der [[Zusatzleistungen]]. Zur Aktivierung erhalten Sie Zugriff auf ein Word-Dokument, das die Details der Nutzung sowie möglich Parameter beschreibt. Die Programmierung auf Seiten der Hochschule muss durch eine zuständige Person der Hochschule erfolgen.
 
Die Aktivierung der API erfolgt auf Wunsch durch [[TrOn]] und ist eine der [[Zusatzleistungen]]. Zur Aktivierung erhalten Sie Zugriff auf ein Word-Dokument, das die Details der Nutzung sowie möglich Parameter beschreibt. Die Programmierung auf Seiten der Hochschule muss durch eine zuständige Person der Hochschule erfolgen.
 +
 +
 +
 +
  
 
==Aufruf der API==
 
==Aufruf der API==
 
Die API wird aufgerufen über eine externe Seite, die außerhalb des TraiNex-Servers, aber in Deutschland, liegt.  
 
Die API wird aufgerufen über eine externe Seite, die außerhalb des TraiNex-Servers, aber in Deutschland, liegt.  
Die Seite kann in z.B. php, html oder ColdFusion geschrieben sein. In ColdFusion würde der Aufruf z.B. wie folgt aussehen:
+
Die Seite kann in z.B. php, html oder ColdFusion geschrieben sein. Details sind beschrieben in der Dokumentation, die anforderbar ist.
[[Datei:api_demo_php.JPG|thumb|right|PHP-Beispiel-Code|250px]]
 
<cfhttp method="get" url="https://trainexXX.de/KUNDENVERZEICHNIS/api/index.cfm" username="api_User_Name" password="Api_PAsswort" result="res"><BR>
 
<cfhttpparam type="url" name="m" value="students" /><BR>
 
<cfhttpparam type="url" name="course" value="" /><BR>
 
<cfhttpparam type="url" name="mat" value="12345,testnr" /><BR>
 
<cfhttpparam type="url" name="format" value="json" /><BR>
 
</cfhttp><BR>
 
Ergebnis: Ruft die Studierenden ("m=students") aller Studiengänge ("course=''") mit der Kundennummer "12345" und "testnr" auf und gibt es als JSON (format=json) aus.
 
 
 
<HR>
 
<cfhttp method="get" url="https://trainexXX.de/KUNDENVERZEICHNIS/api/index.cfm" username="api_User_Name" password="Api_PAsswort" result="res"><BR>
 
<cfhttpparam type="url" name="m" value="students" /><BR>
 
<cfhttpparam type="url" name="course" value="BABW05VZ" /><BR>
 
<cfhttpparam type="url" name="mat" value="" /><BR>
 
<cfhttpparam type="url" name="format" value="csv" /><BR>
 
</cfhttp><BR>
 
Ergebnis:Gibt die Studierenden des Studienganges BABW05VZ im csv-Format aus.
 
<HR>
 
Im Standard werden wenig Details vom Studierenden oder Studiengang übergeben.
 
Der Umfang der Details kann durch den Parameter FETCH bestimmt werden.
 
<HR>Wen mehrere Standorte verwendet werden, kann mittels des Parameters BRANCH der verwendete Standort bestimmt werden.
 
course, mat und format kann die Hochschule natürlich auch als URL-Variable übergeben an die externe Seite.
 
  
 
==Sicherheit==
 
==Sicherheit==
 
Username und Passwort sowie API-ID werden festgelegt durch [[TrOn]] und dem Kunden mitgeteilt.
 
Username und Passwort sowie API-ID werden festgelegt durch [[TrOn]] und dem Kunden mitgeteilt.
Der Aufruf erzeugt Basic-Auth-Credentials. <BR>
+
Der Aufruf erzeugt Basic-Auth-Credentials. Jede Nutzung der API wird inkl. IP-Adresse registriert/protokolliert.  Die aufrufende IP-Adresse kann definiert sein. Ein Aufruf von außerhalb Deutschlands/Östereichs ist erschwert und nicht automatisch möglich.<BR>
Das Zusatz-Passwort wird systematisch und automatisch in definierten Zeitabständen (z.B. täglich) geändert.<BR>
+
Zeiten des Abrufs können festgelegt sein (z.B. nur abends zwischen 18 und 19 Uhr). Details sind beschrieben in der Dokumentation, die anforderbar ist.
An einer Stelle wird dazu von einer zuständigen, programmierenden Person benötigt der Wert day_of_year_heute. Dieser ist z.B. am 20.2. die Zahl 51.
 
<BR>
 
Jede Nutzung der API wird inkl. IP-Adresse registriert/protokolliert.  Die aufrufende IP-Adresse kann definiert sein. <BR>
 
Ein Aufruf von außerhalb Deutschlands/Östereichs ist erschwert und nicht automatisch möglich.<BR>
 
Zeiten des Abrufs können festgelegt sein (z.B. nur abends zwischen 18 und 19 Uhr).
 
  
 
==Output==
 
==Output==
Zeile 53: Zeile 50:
 
Die API liefert Rohdaten in alternativen Formaten. Zu den Rohdaten gehören die Personal-Daten der Nutzenden wie Name, Geburtsdatum, Studiengruppenzugehörigkeit, Matrikelnummer oder Vorsemester. Der Output enthält nur die in Datenbanken gespeicherten Felder und keine berechneten Felder. Beispiel: Die Anzahl der Vorsemester ist in TraiNex gespeichert und kann direkt abgerufen werden. Die Anzahl der Fachsemester hingegen wird berechnet aus z.B. Studienstart, Studiengangssemester und Vorsemester etc. und kann nicht direkt abgerufen werden.<BR>
 
Die API liefert Rohdaten in alternativen Formaten. Zu den Rohdaten gehören die Personal-Daten der Nutzenden wie Name, Geburtsdatum, Studiengruppenzugehörigkeit, Matrikelnummer oder Vorsemester. Der Output enthält nur die in Datenbanken gespeicherten Felder und keine berechneten Felder. Beispiel: Die Anzahl der Vorsemester ist in TraiNex gespeichert und kann direkt abgerufen werden. Die Anzahl der Fachsemester hingegen wird berechnet aus z.B. Studienstart, Studiengangssemester und Vorsemester etc. und kann nicht direkt abgerufen werden.<BR>
 
Ebenfalls nicht direkt abgerufen werden können verbundene Tabellen. Beispiel: Das Modulthema einer Prüfung steht in einer Tabelle und die Noten einer studierenden Person in einer anderen Tabelle. Wenn eine Liste mit "Noten der studierenden Person" über die API abgerufen werden können soll, so ist dies trainexseitig durch [[TrOn]] eine der [[Zusatzleistungen]].
 
Ebenfalls nicht direkt abgerufen werden können verbundene Tabellen. Beispiel: Das Modulthema einer Prüfung steht in einer Tabelle und die Noten einer studierenden Person in einer anderen Tabelle. Wenn eine Liste mit "Noten der studierenden Person" über die API abgerufen werden können soll, so ist dies trainexseitig durch [[TrOn]] eine der [[Zusatzleistungen]].
 +
 +
== Kundenindividuelle API ==
 +
Als Kunden können Sie eigene API (lesend) bauen, wenn Sie eine [[Server-Variante]] wählen, in der die Datenbank kundenseitig betrieben wird.
  
 
== Siehe auch ==
 
== Siehe auch ==
 
*[[Schnittstelle]]
 
*[[Schnittstelle]]
 +
*[[Server-Variante]]
  
 
==Letzte funktionale Änderungen==
 
==Letzte funktionale Änderungen==
 +
*März 2023: Integration der [[API]] zu ChatGPT und anderen Open-AI-Sprachmodellen, um z.B. kreative Überschriftenvorschläge oder Anregungen für Titel oder Gliederungen zu erhalten
 +
*Februar 2023: Neues Sonderrecht 98 für "[[API]]-Zusatzfunktionen".
 +
*Dezember 2022: Erstellung einer Dokumentation, die separat von Kunden, die die API nutzen, angefordert werden kann.
 +
*Oktober 2022: [[API]]: Möglichkeit, den datensparsamen Output durch Zusatzbefehle zu erweitern, um Details von Studiengang oder Studierenden im Output zu erhalten
 +
*Oktober 2022: [[API]]: Möglichkeit, Noten von extern in die Noten-Voreintragstabelle in TraiNex einzutragen
 
*Oktober 2022: [[API]]: Integration des Leistungs-Stands/Einzel-Noten für den Export
 
*Oktober 2022: [[API]]: Integration des Leistungs-Stands/Einzel-Noten für den Export
 
*Oktober 2022: [[API]]: Möglichkeit, auf erzeugte [[Noten]]-Termine-json-Datei von extern zuzugreifen
 
*Oktober 2022: [[API]]: Möglichkeit, auf erzeugte [[Noten]]-Termine-json-Datei von extern zuzugreifen
 
*August 2021: [[API]]: Verbesserung der Anwendungs­programmier­schnittstelle, um Bewerber-Daten auch schreibend in TraiNex einfügen zu können
 
*August 2021: [[API]]: Verbesserung der Anwendungs­programmier­schnittstelle, um Bewerber-Daten auch schreibend in TraiNex einfügen zu können
 
*Januar 2021: Verbesserung der Anwendungs­programmier­schnittstelle, um TraiNex-Daten automatisch-lesend von anderen berechtigten Anwendungen abfragen und verwenden zu lassen (Beispiel: Matrikelnummer-Namens-Liste)
 
*Januar 2021: Verbesserung der Anwendungs­programmier­schnittstelle, um TraiNex-Daten automatisch-lesend von anderen berechtigten Anwendungen abfragen und verwenden zu lassen (Beispiel: Matrikelnummer-Namens-Liste)

Aktuelle Version vom 18. Juli 2024, 06:04 Uhr

Allgemein

Die API (application programming interface, wörtlich ‚Anwendungs­programmier­schnittstelle‘) ermöglicht es, dass andere Programme lesend (oder ggf. in definierten Ausnahmefällen schreibend) an TraiNex angebunden werden. Diese Schnittstelle zur Programmierung von Anwendungen kann von berechtigten Programmierenden der Hochschule genutzt werden, um Daten in strukturierter Form aus den TraiNex-Datenbanken auszulesen (oder ggf. in definierten Ausnahmefällen zu schreiben). Technische Details zur API werden NICHT hier im Wiki sondern in einem separaten Dokument beschrieben, was nur Kunden ausgehändigt wird.


Folgende API-Aufrufe und Funktionen sind grob möglich

  • Lesen von Stammdaten/Adress-Daten/Semesterangaben
  • Lesen von Bewertungen/Noten
  • Aktualisieren/Anlegen von Stammdaten
  • Voreintragung von Bewertungen/Noten
  • Download von vorbereitetem Prüfungstermin-XML
  • weitere Funktionen sind in Entwicklung und beschrieben in der separaten Dokumentation

Haftung, Datenschutz, ADV

Mit der Übergabe der Zugangsdaten für die Schnittstelle, ist es möglich, lesend auf personenbezogene Daten der TraiNex-Nutzer zuzugreifen. Ebenfalls möglich kann es ein, dass Stamm-Daten für Bewerber oder andere Personen oder Noten geschrieben oder verändert oder geleert werden.

  • Die TraiNings-Online GmbH hat Vorkehrungen getroffen, um einen Missbrauch der Schnittstelle zu verhindern.
  • Die TraiNings-Online GmbH übernimmt keinerlei Haftung für eine Ausnutzung der Schnittstelle durch unberechtigte oder berechtigte Dritte.
  • Die Vereinbarung zur Auftragsdatenvereinbarung sowie das Verfahrens-Verzeichnis der datenschutzrelevanten Prozesse sind seitens des Kunden (und nicht durch die TraiNings-Online GmbH) anzupassen.
  • Ohne Zustimmung zum Haftungsausschluss kann die Schnittstelle aus haftungsrechtlichen Gründen nicht in Betrieb genommen werden.

Aktivierung

Die Aktivierung der API erfolgt auf Wunsch durch TrOn und ist eine der Zusatzleistungen. Zur Aktivierung erhalten Sie Zugriff auf ein Word-Dokument, das die Details der Nutzung sowie möglich Parameter beschreibt. Die Programmierung auf Seiten der Hochschule muss durch eine zuständige Person der Hochschule erfolgen.



Aufruf der API

Die API wird aufgerufen über eine externe Seite, die außerhalb des TraiNex-Servers, aber in Deutschland, liegt. Die Seite kann in z.B. php, html oder ColdFusion geschrieben sein. Details sind beschrieben in der Dokumentation, die anforderbar ist.

Sicherheit

Username und Passwort sowie API-ID werden festgelegt durch TrOn und dem Kunden mitgeteilt. Der Aufruf erzeugt Basic-Auth-Credentials. Jede Nutzung der API wird inkl. IP-Adresse registriert/protokolliert. Die aufrufende IP-Adresse kann definiert sein. Ein Aufruf von außerhalb Deutschlands/Östereichs ist erschwert und nicht automatisch möglich.
Zeiten des Abrufs können festgelegt sein (z.B. nur abends zwischen 18 und 19 Uhr). Details sind beschrieben in der Dokumentation, die anforderbar ist.

Output

Ein Output eines Studierenden im JSON-Format kann wie folgt aussehen.

Json1.jpg

Ein Output eines Studierenden im CSV-Format kann wie folgt aussehen. Json2.jpg

Zusatzfelder

Die API liefert Rohdaten in alternativen Formaten. Zu den Rohdaten gehören die Personal-Daten der Nutzenden wie Name, Geburtsdatum, Studiengruppenzugehörigkeit, Matrikelnummer oder Vorsemester. Der Output enthält nur die in Datenbanken gespeicherten Felder und keine berechneten Felder. Beispiel: Die Anzahl der Vorsemester ist in TraiNex gespeichert und kann direkt abgerufen werden. Die Anzahl der Fachsemester hingegen wird berechnet aus z.B. Studienstart, Studiengangssemester und Vorsemester etc. und kann nicht direkt abgerufen werden.
Ebenfalls nicht direkt abgerufen werden können verbundene Tabellen. Beispiel: Das Modulthema einer Prüfung steht in einer Tabelle und die Noten einer studierenden Person in einer anderen Tabelle. Wenn eine Liste mit "Noten der studierenden Person" über die API abgerufen werden können soll, so ist dies trainexseitig durch TrOn eine der Zusatzleistungen.

Kundenindividuelle API

Als Kunden können Sie eigene API (lesend) bauen, wenn Sie eine Server-Variante wählen, in der die Datenbank kundenseitig betrieben wird.

Siehe auch

Letzte funktionale Änderungen

  • März 2023: Integration der API zu ChatGPT und anderen Open-AI-Sprachmodellen, um z.B. kreative Überschriftenvorschläge oder Anregungen für Titel oder Gliederungen zu erhalten
  • Februar 2023: Neues Sonderrecht 98 für "API-Zusatzfunktionen".
  • Dezember 2022: Erstellung einer Dokumentation, die separat von Kunden, die die API nutzen, angefordert werden kann.
  • Oktober 2022: API: Möglichkeit, den datensparsamen Output durch Zusatzbefehle zu erweitern, um Details von Studiengang oder Studierenden im Output zu erhalten
  • Oktober 2022: API: Möglichkeit, Noten von extern in die Noten-Voreintragstabelle in TraiNex einzutragen
  • Oktober 2022: API: Integration des Leistungs-Stands/Einzel-Noten für den Export
  • Oktober 2022: API: Möglichkeit, auf erzeugte Noten-Termine-json-Datei von extern zuzugreifen
  • August 2021: API: Verbesserung der Anwendungs­programmier­schnittstelle, um Bewerber-Daten auch schreibend in TraiNex einfügen zu können
  • Januar 2021: Verbesserung der Anwendungs­programmier­schnittstelle, um TraiNex-Daten automatisch-lesend von anderen berechtigten Anwendungen abfragen und verwenden zu lassen (Beispiel: Matrikelnummer-Namens-Liste)