API: erste Schritte
API einschalten, den ersten Aufruf machen und eine Vorschau rechnen, in fünf Minuten.
Einschalten
- In PenBlitz den Tab „API“ öffnen und „API-Server beim Start mitstarten“ anhaken.
- Die API ist dann unter http://127.0.0.1:8787 erreichbar, nur von diesem Rechner aus.
- 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!"}}'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"}