StudioIntern API

Dokumentation für Entwickler

Version: 0.3

Erklärung für Nicht-Entwickler: Als Inhaber einer Tanz- oder Ballettschule betreiben Sie mit Sicherheit eine eigene Website. Mit der StudioIntern API ist es möglich, Daten aus StudioIntern direkt von oder zu dieser Website zu übertragen. Zum Beispiel können Sie auf diese Weise eine individuelle Lösung für die Einbindung des Kursplans auf Ihrer Website programmieren lassen (wenn Sie SI Web nicht verwenden wollen). Oder Sie übergeben die Angaben aus dem Kontaktformular, welches potentielle Kunden ausfüllen, an StudioIntern – dann müssen Sie es nicht selbst noch einmal eintippen.

Wenn Ihnen das alles zu kompliziert klingt, ignorieren Sie diese Seite einfach (sie ist ohnehin nur für Software-Entwickler von Interesse). Sie können StudioIntern selbstverständlich auch ohne API verwenden.

SI API Dok

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 oder es sind Information schreibbar (nur nicht-destruktiv).
cust
Der Kunden-Bereich (cust - customer). Für Endpoints unterhalb dieses Bereichs ist eine Kunden-Authentifizierung erforderlich. »Kunde« meint in diesem Zusammenhang den Endkunden des Studios.
own
Der Bereich für den Eigentümer (owner) des Tanzstudios/der Ballettschule o.ä. Dieser Bereich ist bisher noch nicht implementiert.

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

Sollte PUT (Update) sein, 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

/pub/user POST

Einen neuen Kunden anlegen

Paths

Your GET endpoint

GET /cust/courses

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

Authorization

Basic User-Auth

header object
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.

Authorization

Basic User-Auth

header string
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.

Authorization

Basic User-Auth

header string
old_password

bisheriges Passwort

query string erforderlich
old_password2

bisheriges Passwort, Kontrolleingabe

query string erforderlich
email

E-Mail-Adresse des Benutzers

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

OK

401 Unauthorized

Unauthorized

404 Not Found

Not Found

405 Method Not Allowed

Method Not Allowed

Precondition Failed

Wird zurückgegeben, wenn neues Passwort nicht mit der Kontrolleingabe übereinstimmt.
417 To less parameters

Expectation Failed

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.

Authorization

Api-Key

header string
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

Für die meisten Installationen von StudioIntern liefern week und weekofdate dasselbe Ergebnis. Genauer gesagt, ist bei den meisten Schulen der Kursplan für jede Woche identisch, aber nicht für alle. Das Verhalten hängt davon ab, ob das Studio die SI-Version mit fortlaufendem Kalender gebucht hat oder nicht (Standard: nein).

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

POST /pub/user

Einen neuen Kunden anlegen

Authorization

Api-Key required

header string
anrede

Anrede

query string [Frau|Herr]
titel

Akademischer Titel (z.B. »Dr.«) des Kunden

query string optional
vorname

Vorname des Kunden

query string
nachname

Nachname des Kunden

query string
adresse

Adresse (Straße, Nr.) des Kunden

query string optional
adresszusatz

Adresszusatz (z.B. »Seitenflügel«) des Kunden

query string optional
plz

Adresse (PLZ) des Kunden

query string optional
ort

Adresse (Ort) des Kunden

query string optional
telefon

Telefonnummer (Festnetz) des Kunden

query string optional
mobil

Telefonnummer (Mobil) des Kunden

query string optional
email

E-Mail-Adresse des Kunden

query string
201 Created

Created

400 Bad Request

Bad Request

401 Unauthorized

Unauthorized

404 Not Found

Not Found

405 Method Not Allowed

Method Not Allowed

417 Expectation Failed

Expectation Failed

500 Internal Server Error

Internal Server Error