MuseumQR · API Dokumentation

MuseumQR JSON API

Diese Dokumentation beschreibt die aktuell gezeigte PHP-API ausführlich, verständlich und mit Beispielen. Sie richtet sich an Entwickler, Admins und Integrationen, die Daten aus MuseumQR lesen oder schreiben wollen.

Zum Schnellstart Zu den Endpunkten Zu den wichtigen Hinweisen

Auf einen Blick

JSON Request Body Authentifizierung per auth_key Lesen & Schreiben über ein Script Rechtebasiert

Die API verarbeitet POST-Requests mit JSON-Body. Alle Aktionen laufen über denselben API-Einstieg. Welche Aktion ausgeführt wird, entscheidet der Inhalt im JSON-Body.

Statusmodell

200 OK 403 Auth failed 406 Invalid request / no rights

Antworten kommen als JSON zurück. Bei Fehlern setzt die API passende HTTP-Statuscodes.

1. Überblick

Die gezeigte API ist als zentrale JSON-Schnittstelle aufgebaut. Es gibt keinen separaten URL-Pfad pro Funktion, sondern einen einzigen Einstiegspunkt. Welche Daten gelesen oder geschrieben werden, hängt davon ab, welche Felder im JSON-Body gesendet werden.

Lesezugriffe
Erfolgen über das Feld get, zum Beispiel "get": "object".
Schreibzugriffe
Erfolgen über das Feld write, zum Beispiel "write": "settings".

2. Basisinformationen

Eigenschaft Beschreibung
Format JSON
Antworttyp application/json
Authentifizierung Per JSON-Feld auth_key
HTTP-Methode Praktisch als POST gedacht, da der Request-Body über php://input eingelesen wird
Backend Datenzugriff über GBDB
Wichtig: Ein exakter URL-Pfad ist im gezeigten Code nicht sichtbar. In dieser Doku wird daher als Platzhalter /api.php verwendet. Ersetze diesen Pfad durch die tatsächliche URL deiner API-Datei.

3. Authentifizierung & Rechte

Jeder Request muss ein Feld auth_key enthalten. Dieser Schlüssel wird gegen die in GBDB::getData("mqr", "api") gespeicherten API-Keys geprüft.

Rechteklassen

Interner Wert Bedeutung Erlaubt
readonly Nur lesen read
write Nur schreiben write
readwrite Lesen und schreiben read,write
Wichtig: Im Quellcode gibt es eine Unstimmigkeit zwischen readonly und read. Die Rechte-Mapping-Konstante nutzt readonly, die Key-Erstellung prüft aber auf read. Mehr dazu weiter unten in den Hinweisen.

4. Request-Aufbau

Jeder Request ist ein JSON-Objekt. Das Minimum ist:

{ "auth_key": "DEIN_API_KEY" }

Dazu kommen je nach Aktion weitere Felder:

Feld Pflicht? Beschreibung
auth_key Ja Authentifizierungsschlüssel
get Bei Lesen Welche Ressource gelesen werden soll
write Bei Schreiben Welche Ressource geschrieben werden soll
Weitere Felder Je nach Aktion Zum Beispiel oid, theme, name, intro, lid, permission

5. Schnellstart

Beispiel: Alle Tours lesen

curl -X POST /api.php \ -H "Content-Type: application/json" \ -d '{ "auth_key": "DEIN_API_KEY", "get": "tours" }'

Beispiel: Settings ändern

curl -X POST /api.php \ -H "Content-Type: application/json" \ -d '{ "auth_key": "DEIN_API_KEY", "write": "settings", "theme": "dark", "name": "MuseumQR", "intro": "Willkommen zur digitalen Tour" }'

6. Leseoperationen

Leseoperationen sind nur möglich, wenn der API-Key das Recht read enthält. Dazu wird ein Request mit dem Feld get geschickt.

POST /api.php get = feedback

Liest Feedback-Daten aus mqr / feedback.

Request

{ "auth_key": "DEIN_API_KEY", "get": "feedback" }

Optional

{ "auth_key": "DEIN_API_KEY", "get": "feedback", "item_id": "123" }

Laut Code ist ein Filter auf item_id vorgesehen.

Erwartete Antwort

{ "success": true, "data": [ { "item_id": "123", "message": "Tolles Objekt" } ] }
Achtung: In der aktuellen Implementierung wird beim Filtern versehentlich über $resp statt über $feedback iteriert. Außerdem wird beim ungefilterten Abruf success: false zurückgegeben, obwohl Daten geliefert werden. Das wirkt wie ein Bug im Quellcode.
POST /api.php get = object

Liest Museumsobjekte. Die Daten werden aus mehreren Quellen zusammengesetzt: objekte, objektimages, objektcontent und objektsrc.

Alle Objekte lesen

{ "auth_key": "DEIN_API_KEY", "get": "object" }

Ein einzelnes Objekt lesen

{ "auth_key": "DEIN_API_KEY", "get": "object", "oid": "OBJ_123" }

Antwort ohne oid

{ "success": true, "data": [ [ ... objekte ... ], [ ... objektcontent ... ], [ ... objektimages ... ], [ ... objektsrc ... ] ] }

Antwort mit oid

{ "success": true, "data": [ { ... objekt ... }, { ... image ... }, { ... content ... }, { ... source ... } ] }
POST /api.php get = settings

Liest die allgemeinen MuseumQR-Einstellungen aus mqr / settings.

{ "auth_key": "DEIN_API_KEY", "get": "settings" }

Antwort

{ "success": true, "data": [ { "id": 0, "theme": "dark", "name": "MuseumQR", "intro": "Willkommen" } ] }
POST /api.php get = langs

Liest verfügbare Sprachen aus expokey / langs.

{ "auth_key": "DEIN_API_KEY", "get": "langs" }
POST /api.php get = tours

Liest verfügbare Touren aus expokey / tours.

{ "auth_key": "DEIN_API_KEY", "get": "tours" }

7. Schreiboperationen

Schreiboperationen sind nur möglich, wenn der API-Key das Recht write enthält. Dazu wird ein Request mit dem Feld write geschickt.

POST /api.php write = api

Erstellt einen neuen API-Key.

Request

{ "auth_key": "DEIN_API_KEY", "write": "api", "permission": "readwrite" }

Erlaubte Werte für permission

read write readwrite

Antwort

{ "success": true, "api_key": "GENERIERTER_KEY" }
Achtung: Im aktuellen Code wird der neue Hash in $k gespeichert, aber beim Datenobjekt versehentlich $key statt $k benutzt. Das bedeutet: Die Rückgabe zeigt wahrscheinlich einen anderen Key als der tatsächlich gespeicherte Wert, oder das Einfügen ist fehlerhaft. Dieser Punkt sollte im Code korrigiert werden.
POST /api.php write = settings

Aktualisiert die MuseumQR-Einstellungen.

Pflichtfelder

theme name intro

Erlaubte Werte für theme

dark light

Request

{ "auth_key": "DEIN_API_KEY", "write": "settings", "theme": "dark", "name": "MuseumQR", "intro": "Willkommen zur Ausstellung" }

Antwort

{ "success": true }
POST /api.php write = langs

Fügt eine neue Sprache in expokey / langs hinzu.

Pflichtfelder

lid name

Request

{ "auth_key": "DEIN_API_KEY", "write": "langs", "lid": "en", "name": "English" }

Antwort

{ "success": true }

Existiert die lid bereits, wird ein Fehler zurückgegeben.

POST /api.php write = tours

Erstellt eine neue Tour in expokey / tours.

Pflichtfelder

name

Request

{ "auth_key": "DEIN_API_KEY", "write": "tours", "name": "Highlights für Kinder" }

Antwort

{ "success": true, "tid": "GENERIERTE_TOUR_ID" }

8. Antwortformat

Die API antwortet grundsätzlich mit JSON. Typische Strukturen:

Erfolg

{ "success": true, "data": ... }

Fehler

{ "success": false, "error": "Fehlermeldung" }

9. Fehlercodes

HTTP-Code Bedeutung Beispiel
200 Erfolgreicher Request Daten gelesen oder geschrieben
403 Authentifizierung fehlgeschlagen {"error":"Auth failed"}
406 Ungültiger Inhalt oder fehlende Rechte Falsches Theme, doppelte LID, keine Schreibrechte

10. Wichtige Hinweise zur aktuellen Implementierung

Diese Doku beschreibt die API so, wie sie nach dem gezeigten Quellcode aktuell gedacht beziehungsweise umgesetzt ist. Beim Lesen des Codes fallen allerdings ein paar Punkte auf, die technisch wichtig sind.

  • Feedback-Filter buggt vermutlich: Beim Filtern nach item_id wird über $resp iteriert, obwohl dort am Anfang noch nichts drin ist. Wahrscheinlich sollte über $feedback gelaufen werden.
  • Feedback ohne Filter liefert success: false: Inhaltlich sieht das nach einem Versehen aus, da gleichzeitig echte Daten zurückgegeben werden.
  • API-Key-Erstellung hat eine Variablenverwechslung: Der neue Schlüssel wird in $k erzeugt, gespeichert werden soll aber $key. Das ist höchstwahrscheinlich falsch.
  • Rechtebezeichnung uneinheitlich: In PERMS steht readonly, bei der Validierung der Erstellung steht aber read. Das sollte vereinheitlicht werden.
  • Die Funktion test_param() ist extern: Sie wird in dieser Datei verwendet, aber nicht gezeigt. Diese Doku nimmt an, dass sie fehlende Pflichtfelder korrekt prüft und bei Fehlern abbricht.
Für eine produktive Nutzung wäre es sinnvoll, diese Punkte im Code zu korrigieren. Danach passt die API-Doku noch sauberer zur tatsächlichen Laufzeit.

11. Kompakte Endpunkt-Referenz

Aktion Body-Feld Beschreibung Recht
Feedback lesen get: "feedback" Liest Feedback, optional nach item_id read
Objekte lesen get: "object" Liest Objekt-Daten, optional nach oid read
Settings lesen get: "settings" Liest allgemeine Einstellungen read
Sprachen lesen get: "langs" Liest ExpoKey-Sprachen read
Touren lesen get: "tours" Liest ExpoKey-Touren read
API-Key erstellen write: "api" Erstellt einen neuen API-Key write
Settings speichern write: "settings" Aktualisiert Theme, Name und Intro write
Sprache anlegen write: "langs" Fügt eine neue Sprache hinzu write
Tour anlegen write: "tours" Erstellt eine neue Tour write
Dokumentation erstellt auf Basis des von dir bereitgestellten PHP-Codes. URL-Pfad und einige Datenstrukturen können je nach Projektstand angepasst werden.