Florian WildeandClaude Opus 5
2e57713a8e
Die Beschreibung sagt auch, was die Schnittstelle bewusst nicht kann — Bereich setzen, Aufgaben loeschen, Zeitbloecke anfassen. Das ist eine Entscheidung und kein Versehen, und wer davorsteht, soll es erfahren, statt es fuer eine Luecke zu halten. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
159 lines
5.3 KiB
Markdown
159 lines
5.3 KiB
Markdown
# Ö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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```json
|
|
{ "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` |
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```bash
|
|
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`
|
|
|
|
```bash
|
|
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.
|