planer/docs/API.md

Öffentliche Schnittstelle

Für fremde Anwendungen, Skripte und Automaten. Wer den Planer selbst bedient, braucht sie nicht.

Basisadresse: <APP_URL>/api/v1

Ausweisen

Jede Anfrage trägt einen Token:

curl -H "Authorization: Bearer planer_ab12cd34_…" \
     https://planer.example.de/api/v1/selbst

Alternativ X-Planer-Token: planer_…, falls das Werkzeug keine Authorization-Kopfzeile kann.

Tokens legst du in der Anwendung unter API an (nur Verwaltung). Der Wert erscheint einmal; danach liegt in der Datenbank nur sein Fingerabdruck. Wer ihn verliert, legt einen neuen an.

Rechte

Drei Stück, und keines schließt ein anderes ein:

Recht	Was damit geht
lesen	Aufgaben abfragen
erfassen	Neue Aufgaben anlegen — mehr nicht
schreiben	Bestehende Aufgaben ändern und abhaken

Ein Dienst, der nur meldet „hier ist etwas Neues", bekommt erfassen und sonst nichts. Das ist der häufigste Fall und der, bei dem ein mitgelesener Token am wenigsten anrichtet.

Fehler

Status	Bedeutung
400	Die Anfrage war fehlerhaft (Feldliste steht in der Antwort)
401	Kein gültiger Token
403	Dieser Token darf das nicht
404	Gibt es nicht

401 sieht immer gleich aus — ob ein Token unbekannt, abgelaufen oder zurückgezogen ist, verrät die Schnittstelle nicht. Von außen soll sich nicht abfragen lassen, welche Tokens es gibt.

Endpunkte

GET /selbst

Wer bin ich, was darf ich? Braucht kein Recht — sonst müsste man raten, ob der Token falsch ist oder nur zu wenig darf.

{ "name": "Wartungsplaner-Import", "rechte": ["erfassen"] }

GET /aufgaben · Recht lesen

Parameter	Standard	Bedeutung
grenze	25	Höchstens 100
versatz	0	Zum Blättern
offen	—	true oder false

{
  "aufgaben": [
    {
      "id": "clx…",
      "titel": "#4711 Drucker klemmt",
      "notiz": null,
      "status": "OFFEN",
      "prioritaet": 3,
      "aufwandMinuten": null,
      "faelligAm": null,
      "quelle": "API",
      "ref": "ticket-4711",
      "url": "https://…",
      "erstelltAm": "2026-03-17T08:20:00.000Z",
      "bereich": null,
      "projekt": null
    }
  ],
  "gesamt": 42,
  "grenze": 25,
  "versatz": 0
}

POST /aufgaben · Recht erfassen

curl -X POST https://planer.example.de/api/v1/aufgaben \
  -H "Authorization: Bearer planer_…" \
  -H "Content-Type: application/json" \
  -d '{"titel":"Drucker klemmt","ref":"ticket-4711"}'

Feld	Pflicht	Bemerkung
titel	ja	bis 200 Zeichen
notiz	nein	bis 4000 Zeichen
ref	nein	Kennung beim Aufrufer — siehe unten
url	nein	Verweis ins Ursprungssystem
faelligAm	nein	JJJJ-MM-TT
prioritaet	nein	1 (dringend) bis 5 (irgendwann)
aufwandMinuten	nein	1 bis 1440

Antwort: 201 mit der angelegten Aufgabe.

ref macht den Aufruf wiederholbar. Zweimal dieselbe Kennung ergibt eine Aufgabe, nicht zwei — der zweite Aufruf frischt Titel, Notiz und Verweis auf. Ohne ref entsteht jedes Mal eine neue Aufgabe; dann hast du es so gewollt.

Benutze ref, wann immer es drüben eine stabile Kennung gibt. Das ist der Unterschied zwischen einer Schnittstelle, die man nach einem Netzhänger gefahrlos wiederholen kann, und einer, die dabei Karteileichen anlegt.

GET /aufgaben/<id> · Recht lesen

PATCH /aufgaben/<id> · Recht schreiben

curl -X PATCH https://planer.example.de/api/v1/aufgaben/clx… \
  -H "Authorization: Bearer planer_…" \
  -H "Content-Type: application/json" \
  -d '{"erledigt":true}'

Änderbar sind titel, notiz, faelligAm, prioritaet, aufwandMinuten und erledigt. Mindestens ein Feld muss dabei sein.

Was die Schnittstelle bewusst nicht kann

• Bereich und Projekt setzen. Was von außen kommt, landet in der Inbox. Die Einordnung ist Sache dessen, der plant, nicht dessen, der meldet — sonst räumt ein fremder Dienst die eigene Ordnung um.
• Aufgaben löschen. Abhaken ja, löschen nein. Ein Fehler im fremden Skript soll keine Planung vernichten.
• Zeitblöcke, Bereiche, Projekte oder Kalender anfassen.

Fehlt dir etwas davon, ist das eine Entscheidung und kein Versehen — sag Bescheid, dann wird darüber geredet.

Protokoll

Jede schreibende Nutzung landet im Protokoll, mit dem Token, über den sie kam. Lesen nicht: Ein Dienst, der im Minutentakt abfragt, würde das Protokoll unbrauchbar machen.

Auch ein abgewiesener Zugriff wird vermerkt. Ein Dienst, der immer wieder an dieselbe Wand läuft, ist entweder falsch eingerichtet oder versucht etwas.