Schnelleinstieg

Der Zugriff auf das CMS erfolgt ausschließlich verschlüsselt (HTTPS) und erfordert immer eine Anmeldung. Für diesen Einstieg wird die Basic-Anmeldung verwendet. Eine Administratorin bzw. ein Administrator hat dazu vorab ein Benutzerkonto angelegt, aber noch kein Kennwort vergeben.

Benutzerkonto anlegen

Eine eigene Oberfläche zur Kontenpflege gibt es nicht: Benutzerkonten sind Datensätze der vordefinierten API cms/users. Auf diese API hat im Allgemeinen nur der Administrator Zugriff. Ein neues Konto CMS_User_01 mit Rechten auf den Namensraum tutorial könnte so angelegt werden:

Das Konto darf im Namensraum tutorial beliebig APIs anlegen, ändern und löschen (namespaceAdmin). Ein Leserecht auf die APIs ist damit eingeschlossen, namespaceUser kann also leer bleiben. Zusätzlich erhält das Konto Vollzugriff auf alle Datensätze aller APIs in diesem Namensraum (apiWrite ist tutorial/*). Auch hier ist das Leserecht eingeschlossen, apiRead kann leer bleiben. Details: Rechte und Konten.

Über die Datenschnittstelle sieht das Anlegen so aus (als Administrator):

curl -X POST -u 'admin:<kennwort>' -H 'Content-Type: application/json' \
  -d '{ "account": "CMS_User_01", "namespaceAdmin": ["tutorial"], "apiWrite": ["tutorial/*"] }' \
  https://cms.example.org/data/cms/users

Bei der ersten Anmeldung legt das Konto sein Kennwort selbst fest: Das bei dieser Anmeldung verwendete Kennwort wird gespeichert. Ein Administrator kann das Kennwort später zurücksetzen oder neu setzen (siehe Kennwörter).

Leere Pflegeanwendung

Nach der Anmeldung an der Pflegeanwendung /form ist zunächst nichts zu sehen, weil noch keine API definiert ist.

Erste API anlegen

Ein HTTP POST an /schema/tutorial/stringonly legt die API stringonly im Namensraum tutorial an. Die Objektklasse enthält nur ein Feld name vom Typ Zeichenkette ("type": "string") mit 4 ("min": 4) bis 40 ("max": 40) Zeichen. Die Pflegeanwendung erhält den Hinweis, dass das Feld in der Tabellenansicht erscheinen soll ("column": true). Die vollständige Beschreibung des Formats steht unter Konfiguration von APIs.

{
    "application": "Tutorial",
    "label": "Hello World",
    "project": "inSynergie CMS",
    "tags": [],
    "fields": {
        "name": {
            "cms": {
                "column": true
            },
            "type": "string",
            "min": 4,
            "max": 40
        }
    }
}

Mit curl, wenn das JSON in stringonly.json liegt:

curl -X POST -u 'CMS_User_01:<kennwort>' -H 'Content-Type: application/json' \
  -d @stringonly.json https://cms.example.org/schema/tutorial/stringonly

Nach einer Aktualisierung erscheint die API in der Pflegeanwendung. In der voreingestellten Projektansicht steht sie als Hello World in der Anwendung Tutorial des Projekts inSynergie CMS. Über die Schaltfläche Namespace View rechts oben wechselt man in die technische Ansicht der Namensräume:

Ein Klick auf den Namensraum tutorial zeigt die bisher einzige API darin:

Ein Klick auf die API stringonly öffnet die Liste ihrer Datensätze, die natürlich noch leer ist. Über die Projektansicht gelangt man direkter zur API. Als Entwickler sollte man sich aber zunächst mit den physikalischen Strukturen vertraut machen.

Erster Datensatz

Nun kann der erste Datensatz in der Oberfläche angelegt werden. Während der Eingabe weist ein gelbes Warnsymbol auf Fehleingaben hin:

Danach erscheint der Datensatz in der Liste. Blättern und Filtern sind möglich, werden hier aber nicht weiter erläutert.

Alle CRUD-Operationen sind auch über die Datenschnittstelle möglich. Ein POST auf /data/tutorial/stringonly legt einen neuen Datensatz an:

{
    "name": "Nicolas"
}

curl -X POST -u 'CMS_User_01:<kennwort>' -H 'Content-Type: application/json' \
  -d '{ "name": "Nicolas" }' https://cms.example.org/data/tutorial/stringonly

Nach einer Aktualisierung der Pflegeanwendung erscheint auch dieser Datensatz in der Liste:

Dasselbe mit fetch

Aus JavaScript, etwa in einer Anwendung im Browser oder in Node.js:

const cms = 'https://cms.example.org'
const auth = 'Basic ' + btoa('CMS_User_01:<kennwort>')

// Datensatz anlegen
const created = await fetch(`${cms}/data/tutorial/stringonly`, {
    method: 'POST',
    headers: { Authorization: auth, 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Nicolas' }),
}).then((res) => res.json())

// Alle Datensätze lesen (erste Seite, siehe Abfragen)
const { items } = await fetch(`${cms}/data/tutorial/stringonly`, {
    headers: { Authorization: auth },
}).then((res) => res.json())

Das CMS erlaubt Zugriffe von beliebigen Ursprüngen (CORS). Kennwörter gehören allerdings nicht in Code, der im Browser ausgeliefert wird. Für Anwendungen im Browser eignen sich eher Kurzzeit-Token oder OIDC.