NAV
shell

Authentifizierung

Für den Zugriff auf die API der Privaten Hochschule für Wirtschaft und Technik (PHWT) wird ein JSON Web Token (RFC 7519) benötigt. Dieser Web Token muss im HTTP-Header als Bearer-Token übertragen werden. Dabei ist die nachfolgende Struktur zu beachten:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Die Erzeugung und Vergabe der Web Token wird automatisiert durch den Server übernommen. Jeder mit einem gültigen PHWT Benutzerkonto (Ilias, studip) kann sich Web Tokens ausstellen lassen. Dazu wird der Benutzername und Passwort des Nutzers benötigt. Nach einer erfolgreichen Anmeldung, liefert der Server einen Access-Token und einen Refresh-Token zurück. Der Access-Token wird für den Zugriff auf die API verwendet und besitzt eine zeitliche Gültigkeit von 15 Minuten. Der Refresh-Token wird verwendet, um einen neuen Access-Token zu erzeugen, wenn dieser nach 15 Minuten seine Gültigkeit verloren hat. Der Refresh-Token hat eine zeitliche Gültigkeit von 3 Stunden. Nach dem zeitlichen Ablauf von 3 Stunden, ist eine erneute Anmeldung des Nutzers erforderlich.

Login

curl --location --request POST 'https://app.phwt.de/api/v1/auth/login' \
--header 'Authorization: Basic <credentials>'

The above command returns JSON structured like this:

{
    "access_token": "<access_token>",
    "refresh_token": "<refresh_token>"
}

Mit diesem API Endpunkt werden die für den Zugriff auf die API benötigten Web Token ausgestellt. Die Authorisierung erfolgt durch HTTP Basic Authentication (RFC 2617). Im HTTP-Header ist der Benutzername und das Passwort des Nutzers Base64 codiert zu übertragen.

HTTP Request

POST https://app.phwt.de/api/v1/auth/login

Header Parameter

Authorization: Basic <credentials>

Refresh

curl --location --request POST 'https://app.phwt.de/api/v1/auth/refresh' \
--header 'Authorization: Bearer <refresh_token>'

The above command returns JSON structured like this:

{
    "access_token": "<access_token>"
}

Mit diesem API Endpunkt wird ein neuer Access-Token mit einer zeitlichen Gültigkeit von 15 Minuten ausgestellt.

HTTP Request

POST https://app.phwt.de/api/v1/auth/refresh

Header Parameters

Authorization: Bearer <refresh_token>

Logout

url --location --request POST 'https://app.phwt.de/api/v1/auth/logout' \
--header 'Authorization: Bearer <access_token>'

The above command returns JSON structured like this:

{
    "msg": "Successfully logged out"
}

Mit diesem API Endpunkt wird der Access-Token und der Refresh-Token des Nutzers für ungültig deklariert.

HTTP Request

POST https://app.phwt.de/api/v1/auth/logout

Header Parameters

Authorization: Bearer <access_token>

Datenzugriffe

Bevor auf die Daten zugregriffen werden kann, muss eine Authentifizierung erfolgen, sodass man einen Access-Token erhält. Dieser ist bei den Abfragen zu verwenden. Sollte dieser abgelaufen sein, kann ein neuer Access-Token über die Refresh-Funktion generiert werden.

Veranstaltungen abfragen

curl --location --request GET 'https://app.phwt.de/api/v1/events' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

The above command returns JSON structured like this:

[
    {
        "Date": "2020-09-28",
        "Event": [
            {
                "Title": "BWL",
                "Kind": "V",
                "Teacher": "Prof. Dr. Beispiel",
                "Starttime": {
                    "Hour": "08",
                    "Minute": "15"
                },
                "Endtime": {
                    "Hour": "09",
                    "Minute": "45"
                },
                "Rooms": [
                    "online"
                ]
            }, 
            ...
        ]
    },
    {
        "Date": "2020-09-30",
        "Event": [
            {
                "Title": "Elektrische Maschinen",
                "Kind": "V",
                "Teacher": "Prof. Dr. A. Beispiel",
                "Starttime": {
                    "Hour": "08",
                    "Minute": "15"
                },
                "Endtime": {
                    "Hour": "09",
                    "Minute": "45"
                },
                "Rooms": [
                    "ZWT 1.04",
                    "ZWT 2.04"
                ]
            }, 
            ...
        ]
    },
    ...
]

Mit diesem API Endpunkt werden alle Veranstaltungen, die zum eigenen Kurs gehören (zb. ET2017), aus der Datenbank gelesen und in JSON-Form zurückgegeben. Der Aufbau der JSON-Rückgabe ist oben dargestellt. Die Veranstaltungen werden in Tage gegliedert, sodass für jeden Tag ein Objekt mit den Datum und einer Liste von Events zurückgegeben wird (Variante 1). Dozenten haben die Möglichkeit sich mehrere Kurse anzeigen zu lassen (Variante 2). Außerdem können Dozenten sich nur ihre Veranstaltungen anzeigen lassen (Variante 3).

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

HTTP Request (Variante 1)

GET https://app.phwt.de/api/v2/events

HTTP Request (Variante 2)

POST https://app.phwt.de/api/v2/events/multiCourse

HTTP Body

[{"id": "1"}, {"id": "3"}, ...]

HTTP Request (Variante 3)

GET https://app.phwt.de/api/v2/events/dozent

Zeitstempel des Stundenplans abfragen

curl --location --request GET 'https://app.phwt.de/api/v1/events/lastUpdate' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

The above command returns JSON structured like this:

{
    "date": 2021-12-24
}

Dieser Endpunkt gibt das Datum wieder, an dem der Stundenplan für den jeweiligen Kurs zuletzt aktualisiert worden ist.

HTTP Request

GET https://app.phwt.de/api/v2/events/lastUpdate

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

Kontakte abfragen

curl --location --request GET 'https://app.phwt.de/api/v1/contacts' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

The above command returns JSON structured like this:

[
    {
        "CardTitle": "Institutsleiter",
        "information": {
        "Name:": "Name des Professors",
        "Email:": "info@phwt.de",
        "Telefon:": "05441/992-0",
        "Organisation:": "PHWT-Institut "
        }
    },
    {
    "CardTitle": "Sekretariat ET/MT",
    "information": {
        "Name:": "Name der Sekretärin",
        "Email:": "info@phwt.de",
        "Organisation:": "Private Hochschule für Wirtschaft und Technik gGmbH",
        "Telefonzentrale:": "04441/915-0",
        "Ort:": "Rombergstraße 40, 49377 Vechta"
        }
    },
    ...
]

Mit diesem API Endpunkt werden alle Kontaktpersonen der PHWT abgefragt. Zurückgegeben wird eine JSON-Response, die eine Liste der verschiedenen Kontaktpersonen entält. Zu jeder Person wir die Stellung und die Kontaktdaten zurückgegeben.

HTTP Request

GET https://app.phwt.de/api/v1/contacts

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

Freie Räume abfragen

[ 
    {
        "room": ["Room 1"],
        "freeTill": "15:45:00"
    },
    {
        "room": ["Room Berlin"],
        "freeTill": "19:00:00"
    },
    {
        "room": ["Room Diepholz"],
        "freeTill": "10:15:00"
    }
]

Dieser Endpunkt wird dazu verwendet, um dem Anwender alle freien Räume zu einer bestimmten Uhrzeit an einem bestimmten Tag zurück zu liefern. So ist es möglich, dass der User während des Tages schaut, welche Räume bis wann frei sind, um sich einen ungestörten Platz zum Arbeiten zu suchen.

HTTP Request

POST https://app.phwt.de/api/v1/freeRoom

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

HTTP Body

[{"date": "2022-12-24", "time": "12:15:00"}]

Kurs abfragen

curl --location --request GET 'https://app.phwt.de/api/v1/course' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

The above command returns JSON structured like this:

# Variante 1
[
{
"courseId": 7,
"courseName": "BWL"
},
{
"courseId": 38,
"courseName": "BWL AgriFood"
},
{
"courseId": 40,
"courseName": "BWL Handel"
},
]
# Variante 2
[
{
"courseId": 7,
"courseName": "BWL"
}
]
# Variante 3
[]

Mit diesem API Endpunkt werden alle Kurse die zu dem Studiengang passen zurück gegeben (Variante 1), sofern für den Benutzter noch kein Kurs ausgewählt wurde. Ansonsten wird eine Liste mit dem gewählten Kurs zurückgegeben (Variante 2). Wenn es nur einen Kurs für den Studiengang gibt, wird eine leere Liste zurückgegeben, da der Benutzer automatisch in diesem Kurs landet. (Variante 3).

HTTP Request

GET https://app.phwt.de/api/v1/course

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

Kurs zuweisen

curl --location --request POST 'https://app.phwt.de/api/v1/course<courseId>' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

The above command returns JSON structured like this:

#Variante 1
[
    "msg" : "user added to course"
]
#Variant 2
[
    "msg" : "course not found"
]

Mit diesem API Endpunkt wird der Benutzer einem Kurs zugewiesen. Wenn bereits eine Zuweisung vorhanden ist, wird diese überschrieben.

HTTP Request

GET https://app.phwt.de/api/v1/course<courseId>

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

Kurszuweisung löschen

curl --location --request DELETE 'https://app.phwt.de/api/v1/course' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

The above command returns JSON structured like this:

[
    "msg" : "removed user from course"
]

Mit diesem API Endpunkt wird der Benutzer aus dem angegebenen Kurs entfernt.

HTTP Request

DELETE https://app.phwt.de/api/v1/course

Header Parameter

Authorization: Bearer eyJ0eXAiO ...

Feedback

Fehler melden

curl --location --request POST 'https://app.phwt.de/api/v1/errors/<errorText>' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

This returns following JSON possibilities:

#Variante 1
[
    "msg": "Error added"
]

#Variante 2
[
    "msg": "Error not added"
]

Mit diesem API-Endpunkt hat der User die Möglichkeit Fehler an das Entwicklungsteam zu melden. Diese Fehler werden in einer Datenbank gesammelt und können abgearbeitet werden. Die Fehler werden mit dem Ersteller gespeichert, sodass auch eine Nachverfolgung des gemeldeten Fehlers möglich ist.

Verbesserung melden

curl --location --request POST 'https://app.phwt.de/api/v1/improvements/<improvementText>' \
--header 'Authorization: Bearer eyJ0eXAiO ...'

This returns following JSON possibilities:

#Variante 1
[
    "msg": "Improvement added"
]

#Variante 2
[
    "msg": "Improvement not added"
]

Mit diesem API-Endpunkt sendet der User einen Verbesserungsvorschlag an das Entwicklungsteam. Diese werden gesammelt und bei der nächsten Entwicklung berücksichtigt. Der User wird mit hinterlegt, damit das Team Kontakt aufnehmen kann, falls Unklarheiten auftreten.

Changelog

Veranstaltungen abfragen

[
    {    "Date": "2020-09-28",
        "Event": [
            {
                "id": 239,
                "Description": "V BWL, Prof. Dr. Beispiel",
                "Starttime": {
                    "Hour": "08",
                    "Minute": "15"
                },
                "Endtime": {
                    "Hour": "09",
                    "Minute": "45"
                },
                "Rooms": [
                    "online"
                ]
            }, 
            ...
       ]
    }
]

Structure changed to:

[
    {    "Date": "2020-09-28",
        "Event": [
            {
                "Title": "BWL",
                "Kind": "V",
                "Teacher": "Prof. Dr. Beispiel",
                "Starttime": {
                    "Hour": "08",
                    "Minute": "15"
                },
                "Endtime": {
                    "Hour": "09",
                    "Minute": "45"
                },
                "Rooms": [
                    "online"
                ]
            }, 
            ...
       ]
    }
]

Zurückgegebene Struktur hat sich geändert.

Http-Request

GET https://app.phwt.de/api/v1/events

änderte sich zu

GET https://app.phwt.de/api/v2/events

shell