Schreibende Endpunkte

Bis V1 waren die Produkt-APIs lesend. Jetzt schreiben sie auch — nach einem Muster, das für jede Sektion gleich ist.

Vier Aktionen, vier Scopes

Ein Scope besteht aus Ressource und Aktion. Die Aktion sagt, was erlaubt ist:

Aktion	Methode	Was sie tut
`:read`	`GET`	Liest Listen und einzelne Einträge.
`:write`	`POST`	Legt einen neuen Eintrag an.
`:update`	`PATCH` / `PUT`	Ändert einen bestehenden Eintrag.
`:delete`	`DELETE`	Entfernt einen Eintrag.

Dazu kommen wenige Vorgangs-Scopes, die kein Datenbestand sind: :release gibt ein Protokoll frei, :export erzeugt einen DATEV-Export.

Die Trennung ist Absicht. Ein Dienst, der Anmeldungen einsammelt, braucht mc.events.registrations:write — aber nicht das Recht, Termine zu löschen. Ein Kassensystem braucht mc.finance.bookings:write, nicht :delete. Der Katalog nennt zu jeder API genau die Scopes, für die es einen Endpunkt gibt: was nicht gelistet ist, existiert nicht.

PATCH ändert nur, was im Körper steht

PATCH ist ein Teil-Update. Felder, die fehlen, bleiben unverändert — du musst einen Datensatz nicht erst lesen, um ein Feld zu ändern.

curl -X PATCH "https://members.api.methacore.de/v1/members/66bcfadc…" \
  -H "Authorization: Bearer mcapi_…" \
  -H "Content-Type: application/json" \
  -d '{ "telephoneNumber": "+49 2832 998877" }'

PUT gibt es dort, wo eine ganze Liste den Bestand bildet: Notfallkontakte, Gruppenpläne. Was du sendest, ist danach der Bestand — auch eine leere Liste.

Unbekannte Felder werden verworfen

Jeder Endpunkt nennt seine Felder. Alles andere im Körper wird ignoriert, nicht gespeichert: ein Client kann sich keine eigenen Felder in fremde Datensätze legen und keine Bindung überschreiben. Die Organisation setzt immer das Token, nie der Körper.

Die Prüfung ist dieselbe wie im Produkt

Schreibende Endpunkte laufen durch denselben Prüfcode wie das Backoffice. Eine Sitzung mit unbekannter Art, eine Abstimmung mit einer Frage ohne zweite Option, eine Anmeldung nach Ende der Anmeldefrist — alles wird abgewiesen, mit demselben Satz, den ein Mensch in der Oberfläche zu lesen bekäme.

Status	Wann
`400`	Der Körper passt nicht: Pflichtfeld fehlt, Typ falsch, Verweis zeigt ins Leere.
`403`	Das Token trägt den nötigen Scope nicht.
`404`	Der Eintrag gehört nicht zu der Organisation, an die dein Token gebunden ist.
`409`	Der Zustand verbietet es: freigegebenes Protokoll, laufende Abstimmung, zugeordnete Buchung, voller Kalender.

409 ist die interessante Antwort: sie sagt nicht „falsch", sondern „nicht jetzt" — und nennt den Grund.

Was bewusst nicht schreibbar ist

Vier Dinge bleiben dem Produkt, und zwar aus demselben Grund: an ihnen hängt mehr als ein Datensatz.

Aufnahme und Austritt von Mitgliedern — Verträge, Beitragsgruppen, Nummernkreise, Kündigungsfristen.
Beitragsläufe — sie erzeugen Rechnungen und Forderungen. Über die API lässt sich nur ein Probelauf wegräumen.
Lastschriften — Geldbewegung mit Fristen und Mandatsprüfung.
Postfächer und Mailversand — ein Konto auf einem Mailserver, kein Eintrag in einer Sammlung.

Das ist keine Lücke, die später zufällig gefüllt wird: kommt einer dieser Vorgänge als Endpunkt, dann mit eigener Aktion (:execute), eigener Dokumentation und eigenem Scope im Katalog.

In der Sandbox gefahrlos üben

Jeder schreibende Endpunkt antwortet auch mit einem Sandbox-Key (ai_sbx_…) — gegen den erfundenen Datensatz deiner Sandbox, auf derselben Adresse. Angelegtes taucht danach in den Listen derselben Sandbox auf, Gelöschtes verschwindet, und ein Zurücksetzen macht alles wieder wie am Anfang. Kein Aufruf erreicht dabei das Produkt.