Vertretungsplan REST-API Dokumentationv1.2

Informationen

Der REST-API Endpoint ist https://vertretungsplan.adriansoftware.de/api/v1/
Es werden GET, POST, PUT & DELETE Anfragen akzeptiert. Jede Antwort enthält den JSON Key "status" mit dem Wert "ok" bei gültiger Anfrage bzw. "error".
Diese API ist für jeden frei zugänglich, unterliegt aber den Nutzungsbedingungen.

API Key

Es wird ein API Key für gesamte Anwendung benötigt, um Anfragen einer Anwendung korrekt zuzuordnen zu können. Der Key kann in den Entwickler Einstellungen erstellt werden. Dieser API Key muss bei jeder Anfrage dabei sein im Header.

API Limits

Es können maximal 20 Anfragen pro Minute und pro Nutzer (IP-Adresse) an die API gesendet werden. Jede weitere Anfrage wird ignoriert und löst folgenden 429 Error aus.
Nach den verbleibenden 60 Sekunden wird der Zähler automatisch zurückgesetzt.

{
    "status": "error",
    "description": "Too Many Requests. Maximale Anzahl von 20 Anfragen/min/Benutzer wurde überschritten. Bitte versuche es gleich erneut"
}

Manche Methoden erfordern bestimmte Rechte bzw. sind nur für bestimmte Benutzerrollen erlaubt. Erklärungen zu den gekennzeichneten Methoden:

(keine) Keine Beschränkung. Jeder Token akzeptiert.
Nur die UserID verwenden, welche mit dem generierten Token übereinstimmt verwenden, sonst Token eines Administrator Accounts benötigt.
Token eines Administrator oder Lehrer Accounts benötigt.
Token eines Administrator Accounts benötigt.
API Methoden
POST/users/auth

Erstellt einen neuen API Token mit dem gegebenen Benutzernamen & Passwort im Request Body. Ein bestehender API Token wird gelöscht.
Der erhaltene Token und die UID muss bei jeder Anfrage im Header stehen. Der Token ist eine Stunde lang gültig, danach verfällt er. expires ist ein Timestamp des Zeitpunktes an dem der Token verfällt.

Anfrage / Header / Request Body
POST https://vertretungsplan.adriansoftware.de/api/v1/users/auth
{
	"username": "DerBenutzernameHier",
	"password": "DasPasswortHier"
}
Header Value
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "token": "8b9c2baab20aba3b28138d3e480276ab1ef42b083d84f847b43ccaeae1ff7b98ae5dbe96c796ca224d0504f4c287e9e6",
    "uid": 1,
    "expires": "1552997446"
}
Achtung Jeder kann mit dem Token die API und somit den Account benutzen, daher muss dieser unbedingt an einem sicheren Ort aufbewahrt werden.
Der Token verfällt nach 1 Stunde.
DELETE/users/auth

Entfernt den API Token mit der gegebenen UID & dem Token im Header. Nützlich für z.B. Logouts.

Anfrage / Header / Request Body
DELETE https://vertretungsplan.adriansoftware.de/api/v1/users/auth
Header Value
Token b382d53e3cba4a1ca7f6e9b49a35f923ae8693ed841dd8eb78fc1d8215890f7352adaeade9a03af483fb91d38a85cfb8
UID 812
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok"
}
GET/plan/{Datum}

Gibt den Vertretungsplan für das angegebene Datum zurück.
Das Datum muss folgendermaßen formatiert sein: DD-MM-YYYY z.B. 17-03-2019

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/plan/17-03-2019
Header Value
Token e02897718a3c09ab4f0664a07dcb9ccf706c2fbc69fe5022bde98629ced2975bbfcdf2a48a66589c53d2c8fbcb15b456
UID 31
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "plan": [
        {
            "0": 1,
            "1": "2019-03-17",
            "2": "11",
            "3": 1,
            "4": "d3",
            "5": "WP",
            "6": "Vertretung",
            "7": "",
            "id": 1,
            "datum": "2019-03-17",
            "klasse": "11",
            "stunde": 1,
            "fach": "d3",
            "lehrer": "WP",
            "art": "Vertretung",
            "hinweis": ""
        },
        {
            "0": 4,
            "1": "2019-03-17",
            "2": "12",
            "3": 2,
            "4": "bi2",
            "5": "NA",
            "6": "Raumwechsel N301",
            "7": "",
            "id": 4,
            "datum": "2019-03-17",
            "klasse": "12",
            "stunde": 2,
            "fach": "bi2",
            "lehrer": "NA",
            "art": "Raumwechsel N301",
            "hinweis": ""
        },
        {
            "0": 2,
            "1": "2019-03-17",
            "2": "12",
            "3": 3,
            "4": "M1",
            "5": "BLE",
            "6": "EVA",
            "7": "Seite 123 Nr.1",
            "id": 2,
            "datum": "2019-03-17",
            "klasse": "12",
            "stunde": 3,
            "fach": "M1",
            "lehrer": "BLE",
            "art": "EVA",
            "hinweis": "Seite 123 Nr.1"
        }
    ],
    "anzahl": 3,
    "datum": "17.03.2019"
}
POST/plan/{Datum}

Erstellt einen neuen Vertretungsplan Eintrag für das angegebene Datum.
Das Datum muss folgendermaßen formatiert sein: DD-MM-YYYY z.B. 17-03-2019

Anfrage / Header / Request Body
POST https://vertretungsplan.adriansoftware.de/api/v1/plan/17-03-2019
Header Value
Token b382d53e3cba4a1ca7f6e9b49a35f923ae8693ed841dd8eb78fc1d8215890f7352adaeade9a03af483fb91d38a85cfb8
UID 970
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
    "klasse": "11",
    "stunde": 1,
    "fach": "d3",
    "lehrer": "WP",
    "art": "fällt aus",
    "hinweis": "EVA im Sek"
}
Antwort
{
    "status": "ok"
}
POST/users

Erstellt einen neuen Account mit dem gegebenen Benutzernamen, Passwort & Email im Request Body. Sollte der Account bereits bestehen wird false zurückgegeben. Die Response enthält die User ID des erstellten Accounts und ob dieser aktiviert wurde. Verfügbare Benutzerrollen ("type")
1 = Normaler Nutzer
2 = Lehrer*
3 = Administrator*
*Neue Lehrer & Administratoren müssen möglicherweise nach dem Erstellen von einem Admin manuell freigeschaltet werden.

Anfrage / Header / Request Body
POST https://vertretungsplan.adriansoftware.de/api/v1/users
Header Value
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
	"username": "abcxyz",
	"password": "meinpasswort",
    "email": "[email protected]",
    "type": 1
}
Antwort
{
    "status": "ok",
    "uid": 7,
    "activated": true
}
{
    "status": "error",
    "description": "Benutzername bereits vergeben"
}
GET/users

Gibt alle Benutzer zurück.

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/users
Header Value
Token v34tf3tf4tb4f0664a07dcb9ccf706c2fbc69fe5022bde98629ced2975bbfcdf2a48a66589c53d2c8fbcb15b456
UID 714
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "users": [        
        {
            "0": 2,
            "1": "schueler",
            "2": "[email protected]",
            "3": "2019-01-15 15:00:56",
            "4": 1,
            "5": 1,
            "id": 2,
            "username": "schueler",
            "email": "[email protected]",
            "created": "2019-01-15 15:00:56",
            "role": 1,
            "activated": 1
        },
        {
            "0": 3,
            "1": "lehrer",
            "2": "[email protected]",
            "3": "2019-01-24 10:46:21",
            "4": 2,
            "5": 1,
            "id": 3,
            "username": "lehrer",
            "email": "[email protected]",
            "created": "2019-01-24 10:46:21",
            "role": 2,
            "activated": 1
        },
        {
            "0": 4,
            "1": "passwort",
            "2": "[email protected]",
            "3": "2019-03-13 18:38:11",
            "4": 1,
            "5": 0,
            "id": 4,
            "username": "passwort",
            "email": "[email protected]",
            "created": "2019-03-13 18:38:11",
            "role": 1,
            "activated": 0
        },
        {
            "0": 7,
            "1": "abcxyz",
            "2": "[email protected]",
            "3": "2019-03-17 19:42:20",
            "4": 1,
            "5": 1,
            "id": 7,
            "username": "abcxyz",
            "email": "[email protected]",
            "created": "2019-03-17 19:42:20",
            "role": 1,
            "activated": 1
        }
    ]
}
{
    "status": "error",
    "description": "Keine Berechtigung"
}
GET/users/{UserId}/username

Gibt den Nutzernamen für die angegebene User ID zurück.
UserId muss eine ganze Zahl sein.

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/users/512/username
Header Value
Token v34tf3tf4tb4f0664a07dcb9ccf706c2fbc69fe5022bde98629ced2975bbfcdf2a48a66589c53d2c8fbcb15b456
UID 714
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "username": "adrian"
}
{
    "status": "error",
    "description": "Keine Berechtigung"
}
GET/users/{UserId}/email

Gibt die E-Mail für die angegebene User ID zurück.
UserId muss eine ganze Zahl sein.

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/users/836/email
Header Value
Token 8o7234nodi7t3464a07dcb9ccf706c2fbc69fe5022bde98629ced2975bbfcdf2a48a66589c53d2c8fbcb15b456
UID 182
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "email": "[email protected]"
}
GET/users/{UserId}/type

Gibt den Typ des Nutzer mit der angegebenen User ID zurück.
UserId muss eine ganze Zahl sein.
1 = Normaler Nutzer
2 = Lehrer
3 = Administrator

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/users/707/type
Header Value
Token 8j2s773zm0664a07dcb9ccf706c2fbc69fe5022bde98629ced2975bbfcdfcsdrsrcg15b456
UID 999
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "type": 1
}
GET/users/{UserName}/available

Gibt an, ob der Nutzername noch verfügbar ist oder bereits vergeben ist.

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/users/adrian/available
Header Value
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "username": "adrian",
    "available": false
}
PUT/users/{UserId}/username

Ändert den Benutzernamen des Nutzer mit der angegebenen User ID.
UserId muss eine ganze Zahl sein.

Anfrage / Header / Request Body
PUT https://vertretungsplan.adriansoftware.de/api/v1/users/521/username
Header Value
Token iz4ni4ozndo3cb9ccf706c2fbc69fe5022bde98629ced2975bbf5chrhtrchhhr56
UID 16
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
    "username": "meinneuername"
}
Antwort
{
    "status": "ok"
}
PUT/users/{UserId}/email

Ändert die E-Mail des Nutzer mit der angegebenen User ID.
UserId muss eine ganze Zahl sein.

Anfrage / Header / Request Body
PUT https://vertretungsplan.adriansoftware.de/api/v1/users/521/email
Header Value
Token adwd21dozndo3cb9ccf706c2fbc69fe5022bde98629ced2975bbf5chrhtrchhhr56
UID 92
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
    "email": "[email protected]"
}
Antwort
{
    "status": "ok"
}
PUT/users/{UserId}/password

Ändert das Passwort des Nutzer mit der angegebenen User ID.
UserId muss eine ganze Zahl sein.

Anfrage / Header / Request Body
PUT https://vertretungsplan.adriansoftware.de/api/v1/users/66/password
Header Value
Token f6w64t4fozndo3cb9ccf706c2fbc64f74zvze98629ced2975bbf5chrw5u4d64z6
UID 41
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
    "password": "meinneuespasswort"
}
Antwort
{
    "status": "ok"
}
PUT/users/{UserId}/type

Ändert den Account Typ des Nutzer mit der angegebenen User ID. UserId muss eine ganze Zahl sein.
1 = Normaler Nutzer
2 = Lehrer
3 = Administrator

Anfrage / Header / Request Body
PUT https://vertretungsplan.adriansoftware.de/api/v1/users/873/type
Header Value
Token a682384nrdxccf706c2fbc64f74zvze98629ced2975bbf5chrw5u4d64z6
UID 815
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
    "type": 2
}
Antwort
{
    "status": "ok"
}
{
    "status": "error",
    "description": "Keine Berechtigung"
}
POST/users/{UserId}/reset

Schickt dem Nutzer mit der angegebenen User ID eine E-Mail zur Passwortwiederherstellung ("Passwort vergssen").
UserId muss eine ganze Zahl sein.
1 = Normaler Nutzer
2 = Lehrer
3 = Administrator

Anfrage / Header / Request Body
PUT https://vertretungsplan.adriansoftware.de/api/v1/users/873/reset
Header Value
Token a682384nrdxccf706c2fbc64f74zvze98629ced2975bbf5chrw5u4d64z6
UID 815
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok"
}
{
    "status": "error",
    "description": "Keine Berechtigung"
}
GET/settings/{SettingName}

Gibt den Wert der Einstellung SettingName zurück. SettingName muss ein String sein und darf: a-zA-Z_- enthalten.

Anfrage / Header / Request Body
GET https://vertretungsplan.adriansoftware.de/api/v1/settings/regSchueler
Header Value
Token e4ac315be6cf61774e8af39bf3d22a4296a2729394242b67e575e0e98d30421d53e7ab74
UID 713
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
Antwort
{
    "status": "ok",
    "value": "1"
}
PUT/settings/{SettingName}

Ändert den Wert der Einstellung SettingName. SettingName muss ein String sein und darf: a-zA-Z_- enthalten. Die Antwort enthält den Setting name sowie dessen neuen Wert.
Die Einstellung wird erstellt, falls sie nicht vorhanden ist.

Anfrage / Header / Request Body
PUT https://vertretungsplan.adriansoftware.de/api/v1/settings/regLehrer
Header Value
Token wdt4fe6cf61774e8af39bf3d22a4296a2729394242b67e575e0e98d30421d53e7ab74
UID 494
API-Key eef2bc183e95a992bc1f5bd768993d89152c375b69a4e63f12b21b43b4e23aa7
{
    "value": "0"
}
Antwort
{
    "status": "ok",
    "setting": "regLehrer",
    "value": "0"
}