Allgemeine Konfiguration von APIs

Der Zugriff auf die Konfiguration einer API erfolgt über den HTTP/POST Endpunkt /schema/<namespace>/<api>. Die Konfiguration selbst wird im JSON Format übermittelt.

POST legt eine neue API an - existiert diese bereits, wird ein Fehler (400) ausgelöst. Beim Anlegen wird das verwendete Konto als Eigentümer der API vermerkt.
DELETE entfernt eine existierende API - alle zugeordneten Datensätze werden unwiderruflich entfernt.
PUT verändert eine existierende API - existiert diese nicht, wird ein Fehler (400) ausgelöst. Die Datensätze werden dabei nicht verändert, sollte eine Migration notwendig sein, muss diese geeignet durchgeführt werden - e.g. erst eine gemeinsame (alt & neu) Konfiguration einspielen, Datensätze anpassen, Konfiguration auf den endgültigen Stand bringen. Das kann unterschiedlich aufwändig sein und wird aktuell nicht adressiert.
GET meldet die aktuelle Konfiguration einer API.

Das CMS bietet weitere HTTP/GET Abfragen:

/schema meldet alle Namensräume (Feld von Zeichenketten) bei denen das Konto mindestens eine API sehen darf. Eine Einschränkung (Filter) oder Sortierung ist nicht vorgesehen – es werden immer alle Namensräume gemeldet.
/schema/tutorial liefert alle APIs (Feld von Zeichenketten) in einem Namensraum (hier tutorial), auf die das Konto mindestens Leserecht hat. Die Liste der APIs ist nicht sortiert.

Die grundsätzliche Struktur einer Konfiguration sieht wie folgt aus:

{
    "fields": {
        "prop1": { "type": "type1" },
        "prop2": { "type": "type2" ),
        ...
    },
    "hideId": true,
    "previewUrl": "https://www.preview.net?ns={namespace}&api={api}&id={id}&lang={language}"
}

Hier würde eine API mit Datensätzen definiert, wobei jeder Datensatz zwei verpflichtende Felder besitzt: prop1 verwendet den Datentyp type1, prop2 den type2.

Im Beispiel sind neben der Strukturbeschreibung noch weitere optionale Parameter angegeben, die von der generischen Pflegeanwendung / CMS-Frontend ausgewertet werden:

hideId kann gesetzt (true) werden, um die Anzeige der internen, automatisch erstellten eindeutigen Kennung (_id) zu unterdrücken.
singleton wird für APIs verwendet (true), die nur einen einzelnen Datensatz enthalten dürfen – oft verwendet für Konfigurationen. Ist noch kein Datensatz in der API eingetragen, so wird in der Pflegeoberfläche nur eine Schaltfläche zum Anlegen des ersten und einzigen Datensatzes angeboten. Sobald ein solcher existiert wird beim Aufrufen der API in der Pflegeoberfläche dieser direkt zur Bearbeitung angeboten. Tatsächlich kann er auch wieder gelöscht werden, wobei dann beim nächsten Aufruf wieder die Schaltfläche zum Anlegen angeboten wird – das CMS erlaubt es nicht, mehr als einen Datensatz anzulegen.
previewUrl führt, falls vorhanden, dazu, dass eine Schaltfläche zur Vorschau für einen Datensatz angezeigt wird in der Editier-Ansicht eines Datensatzes im CMS-Frontend. Beim Aufruf der konfigurierten Preview-URL wird der in geschweiften Klammern gezeigte Platzhalter ersetzt (namespace, api, id und language) - es müssen natürlich nicht alle Platzhalter verwendet werden. Bsp. für einen konkreten Aufruf der previewUrl¹: https://www.preview.net/?ns=tutorial&api=stringonly&id=4381dc2c-0ca4-4b05-86c2-212ca14962df.

https://www.preview.net ist nur ein fiktives Beispiel. Um eine Preview sehen zu können, muss ein eigener Server laufen, welcher Kenntnis und Zugang zum CMS hat und die Daten zum angefragten Datensatz beim CMS jeweils abfragt, um sie dann darstellen zu können. ↩

Footnotes​

Footnotes