Konfiguration von APIs (Objektklassen)

Endpunkte

Die Konfiguration einer API erfolgt über /schema/<ns>/<api>, hier für den Namensraum ns und die API api. Die Beschreibung wird im JSON-Format übermittelt (Aufbau siehe unten).

Methode	Wirkung
`POST /schema/<ns>/<api>`	Legt eine neue API an. Existiert sie bereits, wird ein Fehler (400) gemeldet. Das verwendete Konto wird als Eigentümer der API vermerkt.
`PUT /schema/<ns>/<api>`	Ersetzt die Beschreibung einer existierenden API vollständig. Existiert sie nicht, wird ein Fehler (400) gemeldet.
`DELETE /schema/<ns>/<api>`	Entfernt eine API. Alle zugehörigen Datensätze werden unwiderruflich gelöscht.
`GET /schema/<ns>/<api>`	Liefert die aktuelle Beschreibung der API.
`GET /schema/<ns>`	Liefert die Namen aller APIs im Namensraum, auf deren Datensätze das Konto mindestens Leserecht hat (unsortiert).
`GET /schema`	Liefert alle Namensräume, für die das Konto `namespaceAdmin` oder `namespaceUser` hat und in denen bereits eine API existiert. Filter oder Sortierung gibt es nicht.
`GET /projects`	Liefert die Beschreibungen aller sichtbaren APIs, jeweils ergänzt um `namespace` und `api`. Grundlage der Projektansicht.

Zur Sichtbarkeit siehe auch Wie Rechte zusammenwirken.

POST, PUT und DELETE antworten mit { "id": "…" }, der internen Kennung der API.

Beispiele mit curl:

CMS=https://cms.example.org
USER='CMS_User_01:<kennwort>'

# Anlegen, Ändern, Löschen (Beschreibung in api1.json)
curl -X POST   -u "$USER" -H 'Content-Type: application/json' -d @api1.json "$CMS/schema/tutorial/api1"
curl -X PUT    -u "$USER" -H 'Content-Type: application/json' -d @api1.json "$CMS/schema/tutorial/api1"
curl -X DELETE -u "$USER" "$CMS/schema/tutorial/api1"

# Lesen
curl -u "$USER" "$CMS/schema"
curl -u "$USER" "$CMS/schema/tutorial"
curl -u "$USER" "$CMS/schema/tutorial/api1"

Namen

Was	Regel	Beispiel
Namensraum	Teile aus Buchstaben und Ziffern, beginnend mit einem Buchstaben, verbunden mit `-`; mehrere solcher Teile durch `.` getrennt	`tutorial`, `kunde-1`, `de.museum.ausstellung`
API	beginnt mit einem Buchstaben, danach Buchstaben, Ziffern, `$ _ . -`, höchstens 257 Zeichen	`api1`, `Bilder_2024`
Feld	beginnt mit einem Kleinbuchstaben, danach wie bei APIs	`name`, `carName`

Änderungen und vorhandene Daten

Ein PUT ändert die Datensätze nicht. Macht eine Änderung eine Migration nötig, muss sie extern erfolgen, z. B. so:

eine gemeinsame Beschreibung einspielen, die alten und neuen Aufbau zulässt,
die Datensätze anpassen,
die endgültige Beschreibung einspielen.

Unkritisch sind neue optionale Felder. Typwechsel, neue Pflichtfelder, verschärfte Grenzen oder entfernte Felder können vorhandene Datensätze ungültig machen. Sie fallen dann erst bei der nächsten Bearbeitung auf.

Aufbau einer Beschreibung

Grundstruktur:

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

Hier hat jeder Datensatz zwei Pflichtfelder: prop1 vom Datentyp type1 und prop2 vom Typ type2. Die verfügbaren Datentypen beschreibt das Kapitel Datentypen.

Vollständig sieht die Beschreibung so aus (TypeScript-Notation):

/** Beschreibung einer API (Objektklasse). */
interface ISchema {
    /** Alle Felder der Objektklasse. */
    fields: Record<string, IField>

    /** Name des Projekts, zu dem die API gehört. */
    project?: string
    /** Anwendung im Projekt, zu der die API gehört. */
    application?: string
    /** Anzeigename der API, sonst wird der technische Name verwendet. */
    label?: string
    /** Beschreibung der API, z. B. mit Hinweisen zum Ausfüllen. */
    description?: string
    /** Schlagworte zur fachlichen Gruppierung. */
    tags?: string[]

    /** Interne Kennung (_id) in der Liste nicht anzeigen. */
    hideId?: boolean
    /** Die API enthält höchstens einen Datensatz. */
    singleton?: boolean
    /** Sprache, mit der die Pflege lokalisierbarer Felder beginnt (sonst en). */
    defaultLanguage?: string
    /** Schaltflächen im Formular eines Datensatzes. */
    buttons?: ISchemaButton[]
    /** Veraltet, stattdessen buttons verwenden. */
    previewUrl?: string

    /** Erweiterungen, derzeit Makros. */
    extensions?: {
        compounds: Record<string, IField>
    }
}

interface ISchemaButton {
    /** Beschriftung. */
    label: string
    /** URL mit Platzhaltern. */
    url: string
    /** true: in neuem Fenster öffnen, false: im Hintergrund aufrufen (Voreinstellung). */
    open?: boolean
    /** Optionales Symbol (Semantic-UI-Name). */
    icon?: string
}

Nur fields ist Pflicht. Unbekannte Eigenschaften werden abgewiesen.

Einordnung

Es wird dringend empfohlen, zumindest Projekt und Anwendung anzugeben. Die Pflegeanwendung gruppiert danach in ihrer Projektansicht.

project: Name des Projekts, z. B. "inSynergie CMS".
application: Anwendung im Projekt, z. B. "Tutorial". Zu einem Projekt gehören meist mehrere Anwendungen (oder Teilprojekte).
label: Anzeigename, z. B. "Lokalisierung". Zu einer Anwendung gibt es fast immer mehrere APIs, etwa für Konfiguration, Vorschlagslisten und Nutzdaten.
description: Bedeutung der API, gern mit Hinweisen zum Ausfüllen, z. B. "Basic configuration of the application.".
tags: beliebige Schlagworte, z. B. ["Exponat", "Unity"].

Projekt und Anwendung sind reine Anzeigeangaben. Rechte richten sich ausschließlich nach Namensraum und API-Name.

Verhalten der Pflegeanwendung

hideId: Die automatisch vergebene Kennung (_id) erscheint nicht als erste Spalte der Liste.
singleton: Die API darf nur einen Datensatz enthalten, typisch für Konfigurationen. Gibt es noch keinen, bietet die Pflegeanwendung nur eine Schaltfläche zum Anlegen an. Sobald er existiert, öffnet die API direkt diesen Datensatz zur Bearbeitung. Er kann auch wieder gelöscht werden, danach erscheint wieder die Schaltfläche zum Anlegen. Mehr als einen Datensatz lässt das CMS nicht zu.
defaultLanguage: Startsprache bei der Pflege lokalisierbarer Felder, ohne Angabe Englisch (en).
extensions: Definition von Makros.

Schaltflächen (`buttons`)

Mit buttons erscheinen im Formular eines Datensatzes rechts oben eigene Schaltflächen. Vor dem Aufruf werden Platzhalter in der URL ersetzt:

Platzhalter	Wert
`{id}`	Kennung (`_id`) des Datensatzes
`{language}`	Kürzel der aktuellen Eingabesprache, ggf. leer
`{api}`	technischer Name der API
`{namespace}`	Namensraum der API

Mit "open": true öffnet sich die URL in einem neuen Fenster bzw. Tab, z. B. für eine Vorschau. Ohne open ruft die Pflegeanwendung die URL im Hintergrund auf, z. B. um in einer Anwendung eine Aktualisierung anzustoßen.

{
    "fields": { "title": { "type": "string" } },
    "buttons": [
        { "label": "Vorschau", "icon": "eye", "open": true, "url": "https://www.preview.net/?ns={namespace}&api={api}&id={id}&lang={language}" },
        { "label": "Exponat neu laden", "url": "https://exponat-1.example/reload?id={id}" }
    ]
}

previewUrl ist die ältere Form einer einzelnen Vorschau-Schaltfläche (entspricht open: true). Sind buttons vorhanden, wird previewUrl ignoriert.

Liste ohne Kennung

Schaltfläche zur Vorschau

Für die Vorschau verwendete URL:

https://www.preview.net/?ns=tutorial&api=preview&id=4381dc2c-0ca4-4b05-86c2-212ca14962df&lang=

Endpunkte​

Namen​

Änderungen und vorhandene Daten​

Aufbau einer Beschreibung​

Einordnung​

Verhalten der Pflegeanwendung​

Schaltflächen (buttons)​