Allgemeingültige API

Grundlegendes

Die neue, allgemeingültige API ermöglicht Zugriff alle Daten und viele Funktionen von cmxOrganize über eine standardisierte API. Dies ermöglicht eine Vielzahl von Anwendungszwecken, wie etwa die Anbindung von Fremdsoftware und anderen Portalen, die Datenübertragung zu oder Funktionserweiterung mit externen Skripten.

Es handelt sich über eine REST-API. Während bereits zu Beginn der volle Umfang an Funktionalität zum Datenabruf und zur einfachen Manipulation von Daten (Erstellen, Ändern, Löschen) bereit steht, wird der darüber hinaus zur Verfügung stehende Funktionsumfang laufend erweitert.

Authentifizierung

Öffentliche Inhalte, also Informationen, die bereits auf der Webseite veröffentlicht sind, können ohne Authentifizierung einfach abgerufen werden. Schreibzugriff ist ohne Authentifizierung nicht möglich.

Um den authentifizierten Zugriff auf die API zu ermöglichen, muss zunächst in cmxOrganize ein API-Zugang für einen Kontakt erstellt werden. Gehen Sie dazu wie folgt vor:

Navigieren Sie zu den Zugängen, indem Sie „Zugänge“ in die globale Suche eingeben.
Erstellen Sie einen neuen Zugang.
Geben Sie dem Zugang einen aussagekräftigen Namen, etwa „API-Zugang für Name der Fremdsoftware“
Hinterlegen Sie im Feld Kontakt den Kontakt, für den der Zugang gelten soll.
Schalten Sie die Eigenschaft „API-Zugang“ auf ja bzw. setzen Sie den Haken. Jetzt wird ein API-Token generiert, mit dem Zugriff auf die API möglich ist. Der Token wird nur einmal angezeigt.
Fügen Sie die Applikation/Objekte „Referenzen“ hinzu und öffnen Sie sie. Führen Sie dann für jedes Berechtigungsset, das Sie diesem API-Zugang zuteilen möchten, folgende Schritte aus:

Klicken Sie auf Referenz erstellen.
Wählen Sie bei „2. verknüpftes Objekt“ zuerst Berechtigungsset und dann das korrekte Berechtigungsset.
Gehen Sie zurück.

Der verknüpfte Kontakt wird dann bei Schreibzugriff bei „erstellt von“, „zuletzt bearbeitet von“ sowie im Schreibvorlauf und in den Aktionen angezeigt. Um die Zugriffe durch Fremdsoftware besser nachvollziehen zu können, empfehlen wir daher, einen Kontakt für jede eingesetzte Fremdsoftware mit API-Zugriff zu erstellen.

Der API-Zugang erhält alle Berechtigungen aus den zuvor verknüpften Berechtigungssets. Schränken Sie nach Möglichkeit den Zugriff auf Daten und Funktionen durch API-Zugänge so weit ein wie möglich. Sollte ein API-Token verloren gehen, kann so der mögliche Schaden eingegrenzt werden.

Bei Verdacht auf Missbrauch eines API-Zugriffs, etwa wenn ein API-Token gestohlen wurde/abgeflossen ist, kann der zugehörige Zugang deaktiviert werden. Der Zugriff ist dann sofort nicht mehr möglich.

Der Token muss dann in einem Bearer-Auth-Header bei jeder Anfrage angegeben werden (vgl. RFC 6750):

Authorization: Bearer Ihr_Token_hier

3 Adressierung und Navigation

Die Basis für alle Endpunkte ist https://beispiel.org/api/, Hier in der Doku wird immer vollständige Anfrage-Pfad genannt. URLs sind case-insensitiv und enthalten keine Leerzeichen.

cmxOrganize ist ein objektorientiertes System, daher erfolgt auch der Zugriff in der API auch nach Klassen und Objekten sowie Klassen- und Objektmethoden. Die Grundfunktionalität (Auflisten, Lesen, Erstellen, Ändern, Löschen) ist für alle Klassen gleich und der Zugriff darauf erfolgt immer auf die gleiche Art, daher werden in dieser Dokumentation nicht alle Endpunkte dafür genannt.

Navigation

Bei den meisten Endpunkten liefert die API proaktiv weitere Endpunkte zurück, die verwendet werden können. Somit kann man sich wie mit Links im Web von Endpunkt zu Endpunkt navigieren. Auch weitere Seiten in der Paginierung von Listen werden so angegeben. Ein Navigationsobjekt hat folgendes Format:

{
    "http_method": "GET",
    "url": "https://beispiel.org/api/veranstaltungen",
    "get_parameter": [
        {
            "name": "seitenindex",
            "optional": true,
            "typ": "number"
        },
        {
            "name": "abfrage",
            "optional": true,
            "typ": "string",
            "beschreibung": "Name der zu verwendenden Abfrage"
        }
    ]
}

Das Array get_parameter wird nur angegeben, wenn es auch mögliche GET-Parameter gibt.

Veraltete Endpunkte

Es kann vorkommen, dass wir Endpunkte (Klassen) umbenennen müssen. Die alten Endpunkte werden in so einem Fall weiterhin verfügbar sein, in den HTTP-Headern wird dann auf den neuen Namen des Endpunktes hingewiesen:

Deprecation: true
 Link: </api/klassen>; rel=latest-version, 
   <https://cmxkonzepte.de/api-doku>; rel=deprecation

4 Datenaustausch

Das Austauschformat ist grundsätzlich JSON.

Nicht-ASCII-Zeichen sowie Sonderzeichen wie Schrägstriche werden von der API über Unicode-Escape-Sequenzen (z. B. u00e4) oder über Backslashes escaped. In der Doku werden für bessere Lesbarkeit die Sonderzeichen direkt dargestellt.

Wenn weitere Formate verfügbar sind, können diese über den Accept-Header angefragt werden
Das Antwortformat wird immer im Content-Type-Header mitgeteilt
Beim Anliefern von Daten (POST/PUT) muss das verwendete Format ebenfalls mit dem Content-Type-Header angegeben werden
Zeitstempel werden im ISO 8601-Format übertragen. Datumsangaben sind im Format JJJJ-MM-TT, Uhrzeit-Angaben in HH:MM:SS, beides in Lokalzeit (in aller Regel Europe/Berlin).

Fehler

Wenn Fehler auftreten, wird dies über den HTTP-Statuscode (4xx und 5xx) angezeigt. Clients müssen nach einer Abfrage den Statuscode prüfen und dementsprechende Fehlerbehandlungen implementieren.

Wenn Fehler auftreten, ist die Antwort immer ein JSON mit dem folgenden Format:

{
    "success": false,
    "message": "Beispielfehlermeldung"
}

Je nach Art des Fehlers können auch noch weitere Informationen enthalten sein.

5 Endpunkte

Listen

GET /api/{klasse-plural}

Wird verwendet, um Objekte eines Typs aufzulisten. Bspw. können alle Veranstaltungen aufgelistet werden mit /api/veranstaltungen. Klassennamen sind immer im Plural, also z. B. veranstaltungen, anmeldungen, kontakte, … Die Ergebnismenge wird beeinflusst durch die verwendete Anfrage, diese bestimmt die ausgegebenen Felder und kann Filter, Gruppierungen und Aggregationen beinhalten. Standard-Anfragen geben üblicherweise alle Objekte ohne Filter aus.

Das Antwortformat sieht wie folgt aus:

{
    "seitenindex": 1,
    "zeilen": 100,
    "zeilen_gesamt": 240,
    "seiten_gesamt": 3,
    "vorherige_seite": null,
    "naechste_seite": {
        "http_method": "GET",
        "url": "https://beispiel.org/api/veranstaltungen?seitenindex=2"
    },
    "daten": [
        {
            "autowert": "cmx682de38637859",
            "nummer": "213.002",
            "phase": "Durchführung",
            "ausgefallen": false,
            // [...]
            "link": {
                "http_method": "GET",
                "url": "https://beispiel.org/api/veranstaltung/cmx682de38637859"
            }
        },
        // [...]
    ],
    "methoden": {
        "beispiel": {
            "http_method": "GET",
            "url": "https://beispiel.org/api/veranstaltung/test"
        }
    }
}

Listen werden immer in Seiten von 100 Einträgen unterteilt. Mit dem GET-Parameter seitenindex kann auf die Seiten zugegriffen werden. Die Endpunkte zur nächsten und vorherigen Seite werden auch als Navigationsobjekt zurück gegeben. Bei jedem aufgelisteten Objekt wird der Endpunkt für die Detailinformationen ebenfalls unter link als Navigationsobjekt. Verfügbare Klassenmethoden (ohne Bezug auf ein bestimmtes Objekt) sind ebenfalls als Navigationsobjekte unter methoden aufgelistet.

Details eines Objektes

GET /api/{klasse}/{autowert}

Listet alle verfügbaren Attribute und deren Werte eines Objektes auf, sowie den eigenen Endpunkt, die Endpunkte von Kindlisten und die Endpunkte von Methoden. Hier wird der Singular verwendet, also z. B. /api/veranstaltung/cmx682de38637859.

{
  "daten": {
    "aktiv": true,
    "aktuelle_teilnehmerzahl": 3,
    "ampeltext": "keine freien Plätze. Anmeldung auf Warteliste möglich.",
    "beginn_datum": "2026-05-21",
    "beginn_uhrzeit": "10:00:00",
    "f_bild": "cmx65a68ce9c0e86",
    "geprueft_am": null,
    "geprueft_von": "",
    "letzte_statusaenderung": "2025-05-21T16:37:10+02:00",
    "name": "Hanne’s und Bärbel’s Strickkurs 🧶",
    "nummer": "213.002"
    // ...
  },
  "link": {
    "http_method": "GET",
    "url": "https://beispiel.org/api/veranstaltung/cmx682de38637859"
  },
  "methoden": {
    "aktualisiere": {
      "http_method": "PUT",
      "url": "https://beispiel.org/api/veranstaltung/cmx682de38637859"
    },
    "loesche": {
      "http_method": "DELETE",
      "url": "https://beispiel.org/api/veranstaltung/cmx682de38637859"
    }
  },
  "kindlisten": {
    "Anmeldungen": {
      "http_method": "GET",
      "url": "https://beispiel.org/api/veranstaltung/cmx682de38637859/anmeldungen",
      "get_parameter": [
        {
          "name": "seitenindex",
          "optional": true,
          "typ": "number"
        },
        {
          "name": "abfrage",
          "optional": true,
          "typ": "string"
        }
      ]
    }
    // ...
  }
}

Kindlisten

GET /api/{klasse}/{autowert}/{kindklasse-plural}

Listet Kindobjekte eines Objektes auf, also beispielsweise alle Anmeldungen zu einer Veranstaltung. Das Rückgabeformat ist das gleiche wie bei normalen Listen, nur ohne Methoden.

Klassenmethoden

GET/POST/PUT /api/{klasse}/{methodenname}

Klassenmethoden sind Methoden, die sich nicht auf ein bestimmtes Objekt beziehen, oder das Objekt der Klasse erst erstellen (bspw. Import aus einem bestimmten Format). Die zu verwendende HTTP-Methode und GET-Parameter werden über das Endpunkt-Objekt mitgeteilt, die zu übertragenden Daten und das Antwortformat ist von der konkreten Methode abhängig. Zukünftig verfügbar werdende Methoden werden nach Möglichkeit in dieser Dokumentation aufgelistet.

Objektmethoden

GET/POST/PUT /api/{klasse}/{autowert}/{methodenname}

Diese Methoden beziehen sich auf ein bestimmtes Objekt. Ansonsten gilt dasselbe wie für Klassenmethoden.

Erstellen von Objekten

POST /api/{klasse}

Erstellt ein Objekt von der angegebenen Klasse. Es werden alle Standardwerte befüllt. Im Anfrage-Body können Attribute mit zu setzenden Werten angegeben werden, die direkt nach dem Erstellen gesetzt werden sollen:

{
    "name": "Hanne’s und Bärbel’s Strickkurs",
}

Schlüssel = Attributname. Wenn die Werte nicht gesetzt werden können, wird das Objekt nicht erstellt. Das erstellte Objekt wird im Anschluss zurückgegeben.

POST /api/{klasse}/{autowert}/{kindklasse}

Erstellt ein Objekt der Kindklasse, im Kontext des angegebenen Objektes. Bspw: POST /veranstaltung/cmx682de38637859/anmeldung erstellt eine Anmeldung im Kontext der Veranstaltung mit dem gegebenen Autowert. Das heißt, dass die Verknüpfung der Anmeldung zur Veranstaltung schon automatisch gesetzt wird.

Löschen von Objekten

DELETE /api/{klasse}/{autowert}

Löscht das angegebene Objekt. Es werden auch die zugehörigen Kindobjekte mitgelöscht, etwa Termine beim Löschen einer Terminserie.

Setzen von Werten

PUT /api/{klasse}/{autowert}

Setzt die im Body angegebenen Werte. Wenn ein Fehler auftritt, werden keine der angegebenen Werte gesetzt (also entweder wird alles oder nichts gesetzt, keine Teilmenge). Format des Anfrage-Bodys ist wie beim Erstellen von Objekten.

Autor:	Lukas Merk
Erstellt:	11:41 09. März 2026
Letzte Änderung:	08:26 17. März 2026