Kategorien
  • HowTos

JSONAPVueJSI

Auf dieser Seite... (ausblenden)

  1.   1.  JSONAPI
  2.   2.  Ressourcen
    1.   2.1  Struktur von resource objects
  3.   3.  Ressourcen auslesen
  4.   4.  Ressourcen anlegen
  5.   5.  Ressourcen ändern
  6.   6.  Ressourcen löschen
  7.   7.  Mehr

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"
        }
      }
    }
  }
}
[Code herunterladen]

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"
    }
  }
}
[Code herunterladen]

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" } }
    }
  }
}
[Code herunterladen]

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"
        }
      }
    }
  }
}
[Code herunterladen]

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"
    }
  }
}
[Code herunterladen]

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"
        }
      }
    }
  }
}
[Code herunterladen]

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/

Letzte Änderung am March 05, 2021, at 01:22 PM von tgloeggl.