Server und Endpoints

Der Servername für die Endpoints ist immer https://api.studiointern.de/.

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

Nach dem Studio-Hostnamen und vor dem eigentlichen Endpoint steht die Versionsnummer (aktuell immer v1). Studio-Hostname und Versionsnummer werden in dieser Dokumentation nicht immer mit aufgeführt.

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

Paths / Endpoints

"classes": ["2","5","45"]

"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"
      }
    ]
}

"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"
    },
    ...
]

"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",
      "extra": "mit Vorkenntnissen",
      "raum": "Studio 2",
      "more_info": "",
      "hours": "1.5",
      "color": "#33ff66"
    },
    {
      "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",
      "extra": "ab 4 Jahre",
      "raum": "Studio 2",
      "more_info": "",
      "hours": "0.75",
      "color": "#ff3366"
    },
    {
      "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",
      "extra": "ab 4 Jahre",
      "raum": "Saal 1",
      "more_info": "NEU!",
      "hours": "1.5",
      "color": "#FCCCDD"
    },
    ...
]