METIS

Für Entwickler.

METIS besteht aus einer JSON-API und einer Oberfläche, die nichts anderes benutzt als diese API. Was die Oberfläche kann, kann also auch ein eigenes Programm: Mitglieder anlegen, Termine eintragen, Artikel lesen, Formulare auswerten.

Jede Instanz dokumentiert sich selbst

Die Beschreibung der API liegt als OpenAPI-3.1-Dokument bei jeder Instanz unter /v1/openapi.yaml, eine Swagger-Oberfläche zum Lesen und Ausprobieren unter /v1/docs. Beides ist ohne Anmeldung erreichbar. Die Spezifikation beschreibt die Software, nicht die einzelne Instanz: Sie ist vollständig, auch wenn ein Bereich bei Ihnen abgeschaltet ist.

Zum Ansehen genügt eine der Demos: Swagger-Oberfläche von NORDHANG oder die rohe Spezifikation.

Was in der Spezifikation steht

Jede Operation trägt ihren Routennamen als operationId und drei Angaben, die über die Dokumentation hinausgehen:

  • x-metis-permissions nennt die Rechte, die ein Aufruf braucht. Mehrere Einträge heißen: alle. x-metis-any-permissions nennt Rechte, von denen eines genügt.
  • x-metis-module nennt den Funktionsbereich, zu dem die Route gehört. Ist er in einer Instanz abgeschaltet, antwortet die Route dort mit 404.
  • Routen ohne Anmeldung sind mit security: [] gekennzeichnet. Alle anderen erwarten ein Bearer-Token.

Diese Angaben werden bei jedem Testlauf gegen die tatsächlichen Routen geprüft. Eine Route ohne Dokumentation oder eine Dokumentation ohne Route lässt die Tests fehlschlagen. Die Spezifikation ist deshalb kein Nachtrag, sondern Teil des Codes.

Anmeldung und Token

POST /v1/login mit E-Mail und Passwort liefert ein Token, das als Authorization: Bearer … mitgeschickt wird. Ein Aufruf sieht dann genau das, was die angemeldete Person auch in der Oberfläche sieht: Rubriken, Termine und Inhalte werden serverseitig nach ihren Rechten gefiltert.

Wofür das gedacht ist

  • Anbindung an eine bestehende Mitgliederverwaltung, etwa der Abgleich von Konten und Gruppen.
  • Eigene Auswertungen über Termine, Teilnahmen oder Formulareinsendungen.
  • Eine eigene Oberfläche für einen Sonderfall, den das Portal nicht abbildet.

Bei einer eigenen Instanz steht die Dokumentation in der Verwaltung unter „Entwicklung“ verlinkt. Fragen dazu beantworten wir über das Kontaktformular.