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.
{
"data": {
"type": "courseware-blocks",
"id": "1",
"attributes": {
"position": 0,
"visible": false,
"mkdate": "2021-03-02T09:23:45+01:00",
"chdate": "2021-03-02T09:23:45+01:00"
},
"relationships": {
"editor": {
"data": {
"type": "users",
"id": "76ed43ef286fb55cf9e41beadb484a9f"
}
}
}
}
}
3. Ressourcen auslesen
Ein GET
-Request an die URI einer Ressource liefert die JSONAPI-Repräsentation:
GET /jsonapi.php/v1/courseware-structural-elements/1
{
"data": {
"type": "courseware-structural-elements",
"id": "1",
"attributes": {
"position": 0,
"title": "Ein Strukturelement",
"purpose": "",
"payload": {},
"public": 0,
"release_date": null,
"withdraw_date": null,
"can_edit": true,
"can_read": true,
"external_relations": {},
"mkdate": "2021-03-02T09:23:45+01:00",
"chdate": "2021-03-02T09:23:45+01:00"
},
"relationships": {
"children": {
"data": [
{
"type": "courseware-structural-elements",
"id": "2"
}
],
"links": {
"related": "/jsonapi.php/v1/courseware-structural-elements/1/children"
}
},
"[…]": "…"
},
"links": {
"self": "/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.
// POST /jsonapi.php/v1/courseware-block-comments
// Content-Type: application/vnd.api+json
{
"data": {
"type": "courseware-block-comments",
"attributes": {
"comment": "foo"
},
"relationships": {
"user": { "data": { "id": ":userid", "type": "users" } },
"block": { "data": { "id": "1", "type": "courseware-blocks" } }
}
}
}
Es wird eine neue Ressource (mit ID) erstellt und ein Verweis auf unsere neue Ressource:
// HTTP/1.1 201 Created
// Location: /jsonapi.php/v1/courseware-block-comments/1
{
"data": {
"type": "courseware-block-comments",
"id": "1",
"attributes": {
"comment": "foo",
"mkdate": "2021-03-02T09:23:45+01:00",
"chdate": "2021-03-02T09:23:45+01:00"
},
"relationships": {
"block": {
"data": {
"type": "courseware-blocks",
"id": "1"
},
"links": {
"related": "/jsonapi.php/v1/courseware-blocks/1"
}
},
"user": {
"data": {
"type": "users",
"id": "76ed43ef286fb55cf9e41beadb484a9f"
},
"links": {
"related": "/jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f"
}
}
}
}
}
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.
// PATCH /jsonapi.php/v1/courseware-block-comments/1
// Content-Type: application/vnd.api+json
{
"data": {
"type": "courseware-block-comments",
"id": "1",
"attributes": {
"comment": "bar"
}
}
}
Das Resultat spiegelt unsere Änderungen wieder:
// HTTP/1.1 200 OK
{
"data": {
"type": "courseware-block-comments",
"id": "1",
"attributes": {
"comment": "bar",
"mkdate": "2021-03-02T09:23:45+01:00",
"chdate": "2021-03-02T09:24:15+01:00"
},
"relationships": {
"block": {
"data": {
"type": "courseware-blocks",
"id": "1"
},
"links": {
"related": "/jsonapi.php/v1/courseware-blocks/1"
}
},
"user": {
"data": {
"type": "users",
"id": "76ed43ef286fb55cf9e41beadb484a9f"
},
"links": {
"related": "/jsonapi.php/v1/users/76ed43ef286fb55cf9e41beadb484a9f"
}
}
}
}
}
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/