Kumiko 0.412: Webhook-Verträge und generierte HTTP-API-Doku
Apps legen fest, welche Ereignisse sie als Webhook verlassen, und Token-Scopes geben sie frei. kumiko api-docs schreibt die HTTP-API-Referenz und eine OpenAPI-3.1-Datei aus derselben Registry und schlägt in der CI fehl, wenn die Doku hinter dem Code zurückbleibt.
Über persönliche Zugriffstokens konnte eine Kumiko-App ihre HTTP-API schon für Skripte und Monitoring öffnen. Framework 0.412 bringt öffentliche Verträge für die Ereignisse, die eine App als Webhook verschickt, und schreibt die Doku für API und Ereignisse aus dem Code.
Webhook-Ereignisse haben jetzt öffentliche Verträge. r.defineWebhookEvent legt einen an, mit Name, Beschreibung, Payload-Schema und Version. Das ist getrennt vom internen r.defineEvent, damit kein internes Ereignis versehentlich die App verlässt. Eine Entität gibt ihre Ereignisse created, updated und deleted mit webhookEvents: true frei. Die Payload wird aus der Entität abgeleitet und lässt personenbezogene, verschlüsselte und nur schreibbare Felder weg, ebenso die Felder, die ein Feature ausschließt. Ein Token-Scope listet die Ereignisse, die er freigibt. Nennt ein Scope ein Ereignis ohne öffentlichen Vertrag, startet die App nicht.
Der neue Befehl kumiko api-docs erzeugt die Entwickler-Doku aus der Registry und den Token-Scopes. Er schreibt eine openapi.json nur mit den Handlern, die ein Scope erreicht, eine Übersicht, eine Seite zu den Tokens, eine Referenzseite pro Scope und, sobald ein Scope Ereignisse listet, eine events.md mit jeder Webhook-Payload. Die Seiten gibt es auf Englisch, Deutsch, Spanisch, Französisch und Italienisch. Beispiele für Anfragen, Antworten und Webhooks werden in Integrationstests gegen die laufende App aufgezeichnet, die Beispiele in der Doku sind also echte Antworten.
Mit --check schreibt der Befehl nichts und endet mit 1, wenn ein Handler in einem Scope keine Beschreibung hat, wenn eine Maske einen Schreibvorgang auslöst, den kein Scope abdeckt, oder wenn die eingecheckte Doku von dem abweicht, was der Code ergibt. Als CI-Schritt hält das die veröffentlichte API-Doku auf dem Stand des Releases.
Die Zustellung selbst, also Signatur, Wiederholungen und Timeouts, bleibt in der App. Das Framework legt fest, was ein Ereignis enthalten darf, und dokumentiert es.