StudioIntern API

Version: 0.2

Informationen über Kunden und Schüler, die mit StudioIntern.de verwaltet werden.

Server und Endpoints:

Der Servername für die Endpoints ist immer der Hostname des StudioIntern-Kunden, also des Tanzstudios. Beispiel:

https://tanzhausXY.studiointern.de/api/v1.

Es gibt einen allgemeinen Basis-Pfad, der immer für alle Endpoints gilt und in dieser Dokumentation nicht immer mit aufgeführt wird:

/api/v1

Ein vollständiger Endpoint lautet also beispielhaft:

https://tanzhausXY.studiointern.de/api/v1/cust/user

Bereiche für Endpoints

Die API kennt 3 Bereiche:

pub
»Öffentlicher« Bereich. Zur Benutzung ist nur ein API-Key erforderlich. Es gibt pro StudioIntern-Kunde (also pro Hostname) einen API-Key. In diesem Bereich sind lediglich nicht-sensible Informationen verfügbar. Bis jetzt realisiert ist der Endpoint /pub/schedule für den Kursplan.
cust
Der Kunden-Bereich (cust - customer). Für Endpoints unterhalb dieses Bereichs ist eine Kunden-Authentifizierung erforderlich. »Kunde« ist in diesem Zusammenhande der Endkunde des Studios.
own
Der Bereich für den Eigentümer (owner) des Tanzstudios/der Ballettschule o.ä. Dieser Bereich ist bisher lediglich eine Idee...

Authentifizierung

API-Key

Für den Bereich /pub muss ein Header wie folgt gesetzt werden:

Authorization: [API-Key]

Der API-Key ist im Kundenprofil von StudioIntern.de einsehbar, sofern man mit der Rolle »Geschäftsleitung« eingeloggt ist.

User-Auth

Für alle Endpoints des Bereichs cust ist anstelle des API-Keys eine Basic-Authentifizierung erforderlich:

Authorization: Basic [User-Auth]

Dabei folgt [User-Auth] dem bekannten Schema der Basic-Authentifizierung:

base64_encode('[Kundennummer]:[Passwort]')

Die [Kundennummer] ist die vom Studiobetreiber vergebene offizielle Kundennummer, nicht die interne Datenbank-ID.

Das [Passwort] wird ebenfalls vom Studiobetreiber initial erzeugt und dem Kunden mitgeteilt.

Für den POST-Endpoint /cust/user ist zusätzlich die E-Mail-Adresse als Parameter erforderlich.

Summary

Path Operation Description
/cust/courses GET

Liste der von diesem Benutzer (bzw. dessen Schüler) belegten Kurse. Liefert ein Array mit den IDs der Kurse.

/cust/user GET

Verschiedene Informationen über den Benutzer (Kundennummer, Vorname, Nachname, E-Mail, Status)

POST

Hat bis jetzt das Verhalten von PUT (Update), aber aus bestimmten Gründen wird POST verwendet.

Passwort des Benutzers ändern. Bei leerem neuen Passwort wird das Login gelöscht!

/pub/schedule GET

Den öffentlichen Kursplan erhalten

Paths

Your GET endpoint

GET /cust/courses

Liefert alle Kursbelegungen für alle Schüler eines Kunden.

Keine, der Kunde wird anhand der Basic-Auth (im Header) erkannt.

200 OK

OK

204 No Content

No Content

401 Unauthorized

Unauthorized

404 Not Found

Not Found

405 Method Not Allowed

Method Not Allowed

500 Internal Server Error

Internal Server Error

UserAuth
Your GET endpoint

GET /cust/user

Einige Infos über den User, der anhand der Basic-Authentifizierung (im Header) erkannt wurde.

Keine, Benutzer wird anhand des Auth erkannt.

200 OK

OK

204 No Content

No Content

401 Unauthorized

Unauthorized

404 Not Found

Not Found

405 Method Not Allowed

Method Not Allowed

500 Internal Server Error

Internal Server Error

UserAuth

POST /cust/user

Passwort des Benutzers ändern. Vorsicht: Ein leeres neues Passwort löscht das Login komplett!

Nach erfolgreichem Update muss der User-Auth-String geändert werden.

old_password

bisheriges Passwort

query string erforderlich
new_password

neues Passwort

query string optional (wenn leer: Login wird gelöscht)
email

E-Mail-Adresse des Benutzers

query string erforderlich (als zusätzliche Sicherheitsstufe)
200 OK

OK

401 Unauthorized

Unauthorized

404 Not Found

Not Found

417 Expectation Failed

Too less parameters

500 Internal Server Error

Internal Server Error

UserAuth
Get User Info by User ID

GET /pub/schedule

Den Stunden- bzw. Kursplan erhalten. Authentifizierung über API-Key im Header.

period

Zeitraum, für den der Plan ausgegeben werden soll: "today", "week" oder "weekofdate"

week: der Plan für die aktuelle Woche

weekofdate: der Plan für die Woche, in die das übergebene Datum fällt

query string default: today
date

Datum im SQL-Format, für dessen Woche der Plan ausgegeben werden soll.

query string nur bei period=weekofdate erforderlich

Im Moment und für die meisten Schulen liefert week und weekofdate dasselbe Ergebnis. Genauer gesagt, ist bei den meisten Schulen der Kursplan für jede Woche identisch. Das kann sich aber in einer künftigen Version von StudioIntern ändern.

200 OK

OK

204 No Content

No Content

401 Unauthorized

Unauthorized

404 Not Found

Date Not Found

405 Method Not Allowed

Method Not Allowed

417 Expectation Failed

Expectation Failed

500 Internal Server Error

Internal Server Error