docs: Handbuchseite zum Erfassen und Beschreibung der Schnittstelle
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>
This commit is contained in:
Florian Wilde
co-authored by
Claude Opus 5
Claude Opus 5
parent
10b49cf8df
commit
2e57713a8e
+158
@@ -0,0 +1,158 @@
|
||||
# Ö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.
|
||||
Reference in New Issue
Block a user