1.  JSONAPI

JSONAPI ist eine Spezifikation zum Bauen von APIs in JSON.

Seit der v4.5 bietet Stud.IP eine JSONAPI-konforme Schnittstelle an. Es lohnt sich, die verständlich geschriebene Spezifikation zu lesen: https://jsonapi.org/

Hier ein sehr kurzer Überblick über das Grundsätzlichste.

2.  Ressourcen

Stud.IP-Objekte können über die JSONAPI angelegt, ausgelesen, aktualisiert und gelöscht werden. Es ist keine RPC-style Schnittstelle, wir rufen vom Client keine Funktionen beim Server auf.

Stattdessen schicken wir immer vollständige JSON-Repräsentationen von Ressourcen (resource objects) zwischen Client und Server herum. Also ein REST-Schnittstelle.

2.1  Struktur von resource objects

• der Typ einer Ressource: type
• die ID einer Ressource: id
• die Attribute einer Ressource: data
• die Relationen zu anderen Ressourcen: relationships

Fremdschlüssel (range_id, <irgendwas>_id) sind nie Attribute sondern immer Relationen.

3.  Ressourcen auslesen

Ein GET-Request an die URI einer Ressource liefert die JSONAPI-Repräsentation:

GET /jsonapi.php/v1/courseware-structural-elements/1

4.  Ressourcen anlegen

Um eine Ressource anzulegen, brauchen wir eine URI von einer Sammlung dieser Ressourcen: eine Collection-URI. Dort schicken wir mit einem POST-Request eine JSON-Repräsentation unserer neuen Resource hin. Allerdings in der Regel noch ohne ID.

Es wird eine neue Ressource (mit ID) erstellt und ein Verweis auf unsere neue Ressource:

5.  Ressourcen ändern

Ab hier wird es leicht. Wollen wir eine Ressource ändern, ändern wir folgerichtig die JSON-Repräsentation der Ressource (Attribute und/oder Relationen) und schicken sie mit einem PATCH-Request an die URL der Ressource.

Einzelne Attribute und Relationen dürfen ausgelassen werden. Sie werden dann vom Server so behandelt, als wenn sie unverändert bleiben sollen.

Das Resultat spiegelt unsere Änderungen wieder:

6.  Ressourcen löschen

Um Ressourcen zu löschen, schicken wir einen DELETE-Request an die URI der Ressource:

// DELETE /jsonapi.php/v1/courseware-block-comments/1

Der Server antwortet im Erfolgsfall mit:

// HTTP/1.1 204 No Content

7.  Mehr

Die JSONAPI-Spezifikation bietet darüber hinaus noch weitere wichtige Werkzeuge wie zum Beispiel:

• Paginierung,
• Filterung,
• Zusätzliches Ausliefern von Relations-Ressourcen,
• Interaktion mit Relationen als Objekten (mit den Pfeilen)

und noch mehr. Alles dazu unter: https://jsonapi.org/format/