StudioIntern API

Dokumentation für Entwickler

Version: 0.6

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.

Response-Objekt

Alle Daten, die von den Endpoints zurückgegeben werden, sind immer in ein Response-Objekt eingebettet. Dieses hat die folgende Struktur:

class ApiPlainObject
{
	public $message 	= "OK";
	public $code		= 0;
}

Die angeforderten »Nutzdaten« befinden sich dann in zusätzlichen Properties (z.B. »courses«), die diesem Basisobjekt hinzugefügt werden.

Die Property message enthält einen String »OK« oder eine kurze Fehlerbeschreibung; die Property code den Rückgabe-Code des Endpoints. Der Rückgabecode 0 bedeutet: kein Fehler.

Zusammenfassung

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. Falls als Parameter die ID eines Schülers übergeben wird, enthält die Antwort die Kurse nur dieses Schülers, sonst aller Schüler des Benutzers.

/cust/user GET

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

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/courses GET

Liste aller Kurse, die vom Studio angeboten werden. Deaktivierte Kurse (die nicht stattfinden) werden nicht mit geliefert.

/pub/schedule GET

Den öffentlichen Kursplan erhalten

/pub/user POST

Einen neuen Kunden anlegen

Paths / Endpoints

Kursbelegungen erhalten

GET /cust/courses

Liefert alle Kursbelegungen für alle Schüler eines Benutzers oder – wenn eine Schüler-ID als Parameter übergeben wurde – für einen bestimmten Schüler eines Benutzers.

Authorization

Basic User-Auth

header object
sid Schüler-ID Query integer
200 OK

Anfrage wurde fehlerfrei bearbeitet

204 No Content

Kein Fehler, aber die Anfrage lieferte kein Ergebnis

401 Unauthorized

Fehlender Authorisierungs-Header oder Username/Passwort falsch

404 Not Found

Endpoint existiert nicht / falsche Anfrage-URL
oder angefragtes Objekt nicht gefunden (Benutzer, Schüler, Kurs...)

405 Method Not Allowed

Die Anfrage-Methode (GET, POST) ist für diesen Endpoint nicht zulässig.

417 Expectation Failed

Übergebene Parameter sind ungültig, vom falschen Typ oder außerhalb des gültigen Wertebereichs.

500 Internal Server Error

Internal Server Error

Response-Body

Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.

Property Beschreibung Schema Beispiel
classes Array von Kurs-IDs Array[int]
"classes": ["2","5","45"]
UserAuth
Infos über authentifizierten User erhalten

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

Anfrage wurde fehlerfrei bearbeitet

204 No Content

Kein Fehler, aber die Anfrage lieferte kein Ergebnis

401 Unauthorized

Fehlender Authorisierungs-Header oder Username/Passwort falsch

404 Not Found

Endpoint existiert nicht / falsche Anfrage-URL
oder angefragtes Objekt nicht gefunden (Benutzer, Schüler, Kurs...)

405 Method Not Allowed

Die Anfrage-Methode (GET, POST) ist für diesen Endpoint nicht zulässig.

500 Internal Server Error

Internal Server Error

Response-Body

Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.

Property Beschreibung Schema Beispiel
user Objekt { id:integer, firstName:string, lastname:string, email:string, active:boolean, students:Array[object] }
"user":
{
    "id": "12345",
    "firstName": "Monika",
    "lastName": "Muster",
    "email": "moni@muster.de",
    "active": true,
    "students":
    [
      {
        "id": 43,
        "firstName": "Monika",
        "lastName": "Muster",
        "dayOfBirth": "1974-02-27",
        "email": ""
      },
      {
        "id": 44,
        "firstName": "Lisa",
        "lastName": "Muster",
        "dayOfBirth": "2016-10-17",
        "email": "lisa16@web.de"
      }
    ]
}
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
new_password

neues Passwort

query string erforderlich
new_password2

neues Passwort, Kontrolleingabe

query string erforderlich
email

E-Mail-Adresse des Benutzers

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

Anfrage wurde fehlerfrei bearbeitet

204 No Content

Kein Fehler, aber die Anfrage lieferte kein Ergebnis

401 Unauthorized

Fehlender Authorisierungs-Header oder Username/Passwort falsch

404 Not Found

Endpoint existiert nicht / falsche Anfrage-URL
oder angefragtes Objekt nicht gefunden (Benutzer, Schüler, Kurs...)

405 Method Not Allowed

Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.

412 Precondition Failed

Wird zurückgegeben, wenn neues Passwort nicht mit der Kontrolleingabe übereinstimmt.

417 Expectation Failed

Zu wenige oder ungültige Parameter.

500 Internal Server Error

Internal Server Error

Response-Body

Keiner.

UserAuth
Alle aktiven Kurse des Studios mit IDs

GET /pub/courses

Alle derzeit aktiven Kurse des Studios als Liste von Objekten erhalten. Authentifizierung über API-Key im Header.

Authorization

Api-Key

header string
200 OK

Anfrage wurde fehlerfrei bearbeitet

204 No Content

Kein Fehler, aber die Anfrage lieferte kein Ergebnis

401 Unauthorized

Fehlender Authorisierungs-Header

404 Not Found

Endpoint existiert nicht / falsche Anfrage-URL

405 Method Not Allowed

Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.

500 Internal Server Error

Internal Server Error

Response-Body

Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.

Property Beschreibung Schema Beispiel
courses Array von Objekten Array[Object]
"courses":
[
    {
      "id": "1",
      "kurzwort": "Ballett 1",
      "bezeichnung": "Ballett Anfänger Erwachsene",
      "stunden": "1"
    },
    {
      "id": "2",
      "kurzwort": "Modern 2",
      "bezeichnung": "Moderner Tanz Mittelstufe",
      "stunden": "1.5"
    },
    {
      "id": "3",
      "kurzwort": "Kindertanz",
      "bezeichnung": "Kreativer Kindertanz ab 4 Jahre",
      "stunden": "0.75"
    },
    ...
]
Get User Info by User ID

GET /pub/schedule

Den Stunden- bzw. Kursplan für einen bestimmten Zeitraum 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

today: der Plan für den aktuellen Tag

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

Anfrage wurde fehlerfrei bearbeitet

204 No Content

Kein Fehler, aber die Anfrage lieferte kein Ergebnis

401 Unauthorized

Fehlender Authorisierungs-Header

404 Not Found

Endpoint existiert nicht / falsche Anfrage-URL

405 Method Not Allowed

Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.

417 Expectation Failed

Zu wenige oder ungültige Parameter. Z.B. fehlender date-Parameter, wenn für period der Wert »weekofdate« angegeben wurde. Fehlercode erscheint auch bei falsch formatiertem date-Parameter.

500 Internal Server Error

Internal Server Error

Response-Body

Alle Response-Bodies haben immer das allgemeine Response-Objekt als Wrapper. Die nachfolgende Tabelle beschreibt nur die für diesen Endpoint spezifischen Properties dieses Response-Objekts.

Property Beschreibung Schema Beispiel
events Array von Objekten Array[Object]
"events": [
    {
      "id": "23",
      "dow": "Montag",
      "dow_short": "Mo",
      "date": "2021-07-12",
      "start_time": "15:00:00",
      "end_time": "15:55:00",
      "title": "KiBall 2",
      "description": "Kinderballett Grade 2",
      "teacher": "Susanne",
      "more_info": "",
      "raum": "Studio 2"
    },
    {
      "id": "12",
      "dow": "Montag",
      "dow_short": "Mo",
      "date": "2021-07-12",
      "start_time": "16:00:00",
      "end_time": "16:45:00",
      "title": "KiTanz 1",
      "description": "Kreativer Kindertanz",
      "teacher": "Linda",
      "more_info": "",
      "raum": "Studio 2"
    },
    {
      "id": "76",
      "dow": "Montag",
      "dow_short": "Mo",
      "date": "2021-07-12",
      "start_time": "17:00:00",
      "end_time": "18:30:00",
      "title": "Modern E3",
      "description": "Modern Erwachsene, Level 3",
      "teacher": "Heidi",
      "more_info": "",
      "raum": "Saal 1"
    },
    ...
]

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

Der neue Benutzer wurde angelegt.

400 Bad Request

Anfrage kann mit diesen Parameter-Werten nicht ausgeführt werden. Die Ursache ist meist ein bereits existierender Benutzer mit denselben primary oder unique keys. Prüfen Sie die message-Property im Response-Objekt für weitere Informationen.

401 Unauthorized

Fehlender Authorisierungs-Header

405 Method Not Allowed

Die Anfrage-Methode ist für diesen Endpoint nicht zulässig.

417 Expectation Failed

Zu wenige oder ungültige Parameter.

500 Internal Server Error

Internal Server Error

Response-Body

Es wird nur das allgemeine Response-Objekt mit den Properties code und message zurückgegeben.