API: Unterschied zwischen den Versionen

Aus TraiNexWiki
Wechseln zu:Navigation, Suche
(Sicherheit)
(Weitestgehend gegendert)
Zeile 2: Zeile 2:
 
==Allgemein==
 
==Allgemein==
  
Die API (application programming interface, wörtlich ‚Anwendungs­programmier­schnittstelle‘) ermöglicht, dass anderen Programme lesend an TraiNex angebunden werden. Diese Schnittstelle zur Programmierung von Anwendungen kann von berechtigten Programmiereren der Hochschule genutzt werden, um Daten in strukturierter Form aus den TraiNex-Datenbanken auszulesen.<BR>
+
Die API (application programming interface, wörtlich ‚Anwendungs­programmier­schnittstelle‘) ermöglicht, dass andere Programme lesend 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.<BR>
  
Die Aktivierung der API erfolgt auf Wunsch durch [[TrOn]] und ist eine der [[Zusatzleistungen]]. Die API liefert Rohdaten in alternativen Formaten. Zu den Rohdaten gehören die Personal-Daten der Nutzer wie Name, Geburtsdatum, Studiengruppenzugehörigkeit, Matrikelnummer oder Vorsemester. Die Programmierung auf seiten der Hochschule muss durch einen Programmierer der Hochschule erfolgen.
+
Die Aktivierung der API erfolgt auf Wunsch durch [[TrOn]] und ist eine der [[Zusatzleistungen]]. 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. 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 ausserhalb 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. In ColdFusion würde der Aufruf z.B. wie folgt aussehen:
 
[[Datei:api_demo_php.JPG|thumb|right|PHP-Beispiel-Code|250px]]
 
[[Datei:api_demo_php.JPG|thumb|right|PHP-Beispiel-Code|250px]]
Zeile 35: Zeile 35:
 
Der Aufruf erzeugt Basic-Auth-Credentials. <BR>
 
Der Aufruf erzeugt Basic-Auth-Credentials. <BR>
 
Das Zusatz-Passwort wird systematisch und automatisch in definierten Zeitabständen (z.B. täglich) geändert.<BR>
 
Das Zusatz-Passwort wird systematisch und automatisch in definierten Zeitabständen (z.B. täglich) geändert.<BR>
An einer Stelle wird dazu vom Programmierer benötigt der Wert day_of_year_heute. Dieser ist z.B. am 20.2. die Zahl 51.  
+
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>
 
<BR>
 
Jede Nutzung der API wird inkl. IP-Adresse registriert/protokolliert.  Die aufrufende IP-Adresse kann definiert sein. <BR>
 
Jede Nutzung der API wird inkl. IP-Adresse registriert/protokolliert.  Die aufrufende IP-Adresse kann definiert sein. <BR>
Ein Aufruf von ausserhalb Deutschland/Östereich ist erschwert und nicht automatisch möglich.<BR>
+
Ein Aufruf von außerhalb Deutschland/Östereich ist erschwert und nicht automatisch möglich.<BR>
 
Zeiten des Abrufs können festgelegt sein (z.B. nur abends zwischen 18 und 19 Uhr).
 
Zeiten des Abrufs können festgelegt sein (z.B. nur abends zwischen 18 und 19 Uhr).
  
Zeile 51: Zeile 51:
 
==Zusatzfelder==
 
==Zusatzfelder==
 
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, Studiengangsemester und Vorsemester etc. und kann nicht direkt abgerufen werden.<BR>
 
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, Studiengangsemester 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 eines Studierenden in einer anderen Tabelle. Wenn eine Liste mit "Noten eines Studierenden" ü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]].
  
 
==Letzte funktionale Änderungen==
 
==Letzte funktionale Änderungen==
 
*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)

Version vom 30. Juni 2021, 09:02 Uhr

Allgemein

Die API (application programming interface, wörtlich ‚Anwendungs­programmier­schnittstelle‘) ermöglicht, dass andere Programme lesend 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.

Die Aktivierung der API erfolgt auf Wunsch durch TrOn und ist eine der Zusatzleistungen. 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. 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. In ColdFusion würde der Aufruf z.B. wie folgt aussehen:

PHP-Beispiel-Code

<cfhttp method="get" url="https://trainexXX.de/KUNDENVERZEICHNIS/api/index.cfm" username="api_User_Name" password="Api_PAsswort" result="res">
<cfhttpparam type="url" name="m" value="students" />
<cfhttpparam type="url" name="course" value="" />
<cfhttpparam type="url" name="mat" value="12345,testnr" />
<cfhttpparam type="url" name="format" value="json" />
</cfhttp>
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.


<cfhttp method="get" url="https://trainexXX.de/KUNDENVERZEICHNIS/api/index.cfm" username="api_User_Name" password="Api_PAsswort" result="res">
<cfhttpparam type="url" name="m" value="students" />
<cfhttpparam type="url" name="course" value="BABW05VZ" />
<cfhttpparam type="url" name="mat" value="" />
<cfhttpparam type="url" name="format" value="csv" />
</cfhttp>
Ergebnis:Gibt die Studierenden des Studienganges BABW05VZ im csv-Format aus.


course, mat und format kann die Hochschule natürlich auch als URL-Variable übergeben an die externe Seite.

Sicherheit

Username und Passwort sowie API-ID werden festgelegt durch TrOn und dem Kunden mitgeteilt. Der Aufruf erzeugt Basic-Auth-Credentials.
Das Zusatz-Passwort wird systematisch und automatisch in definierten Zeitabständen (z.B. täglich) geändert.
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.
Jede Nutzung der API wird inkl. IP-Adresse registriert/protokolliert. Die aufrufende IP-Adresse kann definiert sein.
Ein Aufruf von außerhalb Deutschland/Östereich ist erschwert und nicht automatisch möglich.
Zeiten des Abrufs können festgelegt sein (z.B. nur abends zwischen 18 und 19 Uhr).

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

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, Studiengangsemester 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.

Letzte funktionale Änderungen

  • 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)