Zum Inhalt springen
PenBlitz
← Entwickler

API: erste Schritte

API einschalten, den ersten Aufruf machen und eine Vorschau rechnen, in fünf Minuten.

Einschalten

  1. In PenBlitz den Tab „API“ öffnen und „API-Server beim Start mitstarten“ anhaken.
  2. Die API ist dann unter http://127.0.0.1:8787 erreichbar, nur von diesem Rechner aus.
  3. Unter http://127.0.0.1:8787/docs liegt die Swagger-Seite, auf der sich jeder Aufruf im Browser ausprobieren lässt.

Ohne die App läuft dieselbe API als Hintergrundprogramm: penblitz-server serve. Mit --mock lässt sie sich ohne Drucker ausprobieren.

Erster Aufruf

Die Zustandsabfrage braucht keinen Schlüssel und zeigt, dass die API läuft:

curl http://127.0.0.1:8787/api/v1/health

{"status":"ok","version":"0.2.0","open_jobs":0,"queue_paused":false}

Eine Vorschau rechnen

Es wird nichts gedruckt. Du bekommst das Blatt als SVG, Warnungen und die voraussichtliche Dauer:

curl -X POST http://127.0.0.1:8787/api/v1/render \
  -H 'Content-Type: application/json' \
  -d '{"template_id": "letter", "record": {"text": "Liebe Anna,\nvielen Dank für deine Bestellung!"}}'

Drucken

Derselbe Inhalt als Auftrag. Ein Datensatz ergibt ein Blatt:

curl -X POST http://127.0.0.1:8787/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{"template_id": "letter", "records": [{"text": "Liebe Anna,\nvielen Dank für deine Bestellung!"}]}'

Mit einem Schlüssel schützen

Erzeuge im Tab „API“ einen Schlüssel. Jeder Aufruf außer der Zustandsabfrage muss ihn dann mitsenden:

curl http://127.0.0.1:8787/api/v1/jobs -H 'X-API-Key: DEIN_SCHLUESSEL'
# oder
curl http://127.0.0.1:8787/api/v1/jobs -H 'Authorization: Bearer DEIN_SCHLUESSEL'

Wer die API ohne Schlüssel für das Netzwerk öffnet (0.0.0.0), lässt jedes Gerät im Netz Druckaufträge starten. Erst einen Schlüssel setzen.

Fehler

Fehlgeschlagene Aufrufe antworten mit dem passenden HTTP-Status und einer Meldung. Der Text folgt der in der App gewählten Sprache; Statuscode und maschinenlesbare Zustände ändern sich nie.

HTTP/1.1 400 Bad Request

{"error": "Vorlage 'lettr' nicht gefunden"}