Für Programme
Boards lesen, ohne sie anzufassen.
Ein Dashboard, Abläufe in n8n oder ein eigenes Skript lesen nexcanvas über eine kleine Schnittstelle: welche Boards es gibt, was sich zuletzt getan hat und ein Bild von jedem Board. Ändern kann ein Programm darüber nichts.
Erst schaltet der Betreiber ein
Ab Werk ist die Schnittstelle aus. Der Betreiber schaltet sie unter Einstellungen, Server, API mit „Konten dürfen API-Token anlegen“ ein. Dort sieht er auch jedes Token mit seinem Namen und Konto, nie das Token selbst, und kann einzelne für immer sperren.
Schaltet er die Schnittstelle wieder aus, antworten alle Token mit 401. Sie bleiben dabei erhalten und gelten wieder, sobald sie wieder an ist.
Jedes Konto macht seine eigenen Token
Unter Mein Konto, Verbindungen legst du mit „Neues Token“ eines an. Du gibst ihm einen Namen, damit du später weißt, wofür es war, und wählst, was es lesen darf und wie lange es gilt.
- Was es liest: alle Bereiche, die du lesen darfst, auch spätere, oder nur bestimmte. Nie mehr, als dein Konto lesen darf.
- Wie lange: 30 Tage, 90 Tage, ein Jahr oder ohne Ablauf. Eine Woche vor dem Ende markiert die Liste das Token.
- Einmal zu sehen: Das Token beginnt mit
nxa_und erscheint nur direkt nach dem Anlegen. nexcanvas behält nur eine Prüfsumme. - Bis zu 20 Token hat jedes Konto.
Die Routen
Jede Anfrage trägt das Token in einer Kopfzeile. Die Antworten sind JSON, das Bild eines Boards ist SVG.
curl -H "Authorization: Bearer nxa_..." https://canvas.example.com/api/v1/boards| Route | Was zurückkommt |
|---|---|
GET /api/v1/me | Für wen das Token spricht, welche Bereiche es lesen darf und die Fassung von nexcanvas |
GET /api/v1/spaces | Die lesbaren Bereiche mit Name, Farbe, Zahl der Boards und deinem Recht dort |
GET /api/v1/boards | Die Boards, zuletzt geänderte zuerst; Parameter space, order (updated oder title) und limit (1 bis 200, ab Werk 50) |
GET /api/v1/boards/{id} | Ein Board, wie in der Liste |
GET /api/v1/boards/{id}/picture.svg | Das Board als kleines Bild im Format 16 zu 10; look (dark oder light) und width (120 bis 1.600 Pixel, ab Werk 480) |
GET /api/v1/dashboard | Zahlen für eine Dashboard-Karte und die fünf zuletzt geänderten Boards |
Zu jedem Board kommen Titel, Bereich, wann es angelegt und zuletzt geändert wurde, von wem, wie viele Dinge darauf liegen, die Adresse zum Öffnen im Browser und der Pfad seines Bildes. Die ganze Beschreibung steht in docs/api.md.
Eine Karte fürs Dashboard
Eine Karte, die die zuletzt geänderten Boards zeigt, fragt ab und zu /api/v1/dashboard, einmal in der Minute reicht. Sie bekommt die Zahl der Bereiche und Boards, wie viele heute und in dieser Woche geändert wurden, und die fünf letzten Boards.
Das Bild jedes Boards holt sie unter seinem Pfad mit derselben Kopfzeile, ein Klick öffnet die Adresse des Boards. Das Bild zeigt Formen, Notizen, Rahmen und Zeichnungen, wie sie sind, Wörter, Fotos und Dateien nur als schlichte Kästen.
Grenzen und Versprechen
| Antwort | Code | Bedeutet |
|---|---|---|
| 401 | api_off | Der Betreiber hat die Schnittstelle nicht eingeschaltet. |
| 401 | token_invalid | Das Token gibt es nicht, es ist abgelaufen, gesperrt oder gelöscht. |
| 403 | origin_refused | Die Anfrage kam von einer Webseite. |
| 404 | not_found | Board oder Bereich gibt es nicht, oder das Token darf es nicht lesen. Beides klingt gleich. |
| 429 | slow_down | Mehr als 600 Anfragen in einer Minute mit diesem Token. Retry-After sagt, wann es weitergeht. |
Cora sagtWas unter /api/v1 steht, bleibt so. Neue Felder können dazukommen, umbenannt oder entfernt wird nichts. Eine Änderung, die ein Programm brechen würde, kommt daneben unter /api/v2.