Werkzeuge

Die Konsole#

Die Konsole liegt unter app.flavoso.com/de/developers. Sie braucht nur ein Flavoso-Konto, keinen Betrieb und kein Abo. Je App gibt es diese Bereiche:

Daneben stehen der Test-Betrieb mit seinen Werkzeugen, für alle deine Apps gemeinsam, und die Einrichtung, bis sie abgeschlossen ist.

Anfrage-Protokoll#

Jede Anfrage deiner App, die ein gültiges Token trägt, steht 14 Tage im Protokoll: Zeit, Betrieb, Methode, Pfad, Operation (operationId), Suchteil, Status, Dauer, X-Request-Id, Fehlercode, Idempotency-Key und User-Agent. Filtern lässt es sich nach Status, Methode, Pfad, Betrieb, Zeitraum und „Nur Test-Betrieb“; die Einzelansicht zeigt eine Anfrage ganz.

Beim Test-Betrieb stehen dazu die Rümpfe von Anfrage und Antwort (bis 16.000 Zeichen). Bei echten Betrieben nie: dort stehen Namen, Telefonnummern und Anschriften von Gästen darin. Kopfzeilen werden nicht gespeichert, also auch kein Token.

Meldet dein Programm einen Fehler, such im Protokoll nach der X-Request-Id der Antwort: dort steht, was angekommen ist.

API-Explorer#

Der API-Explorer führt jede Operation aus der Spezifikation gegen deinen Test-Betrieb aus. Das Token holt er selbst, es gilt 15 Minuten. Du wählst die Operation, füllst Parameter und Rumpf und siehst die Antwort mit ihren Kopfzeilen, dazu denselben Aufruf als curl, Node.js, Python und PHP zum Kopieren.

Was du dort tust, ist echt: eine angenommene Testbestellung ist angenommen, und Ereignisse gehen an deinen Webhook.

Zustellungen der Webhooks#

Unter Webhooks steht jede Zustellung, filterbar nach Stand, Art, Betrieb und Zeitraum. Die Einzelansicht zeigt den Umschlag, die gesendeten Kopfzeilen samt Signatur und jeden Versuch: Zeitpunkt, automatisch oder von Hand, HTTP-Status, Dauer, Fehler und den Anfang der Antwort deines Servers (bis 2.000 Zeichen).

„Erneut senden“ schickt eine Zustellung noch einmal, mit demselben Umschlag und derselben Ereignis-Kennung; das zählt nicht gegen die automatischen Versuche. „Test-Ereignis senden“ schickt jede Art mit Daten aus deinem Test-Betrieb. Mehr unter Webhooks.

Test-Token#

„Test-Token erzeugen“ unter Zugangsdaten gibt ein Access-Token und ein Refresh-Token für deinen Test-Betrieb aus, ohne Umweg über den Browser. Das Access-Token gilt eine Stunde und trägt die Rechte deiner App; du kannst es auf weniger Rechte einengen. Das Refresh-Token gilt 180 Tage ab der letzten Nutzung und wird bei jeder Nutzung getauscht; erneuert wird am Token-Endpunkt, mit der Anmeldung deiner App. Die Konsole zeigt beide Tokens genau einmal. Für einen echten Betrieb gibt es kein Test-Token: dort entscheidet der Inhaber.

OpenAPI-Spezifikation#

Die ganze Schnittstelle als OpenAPI 3.1, ohne Anmeldung: https://api.flavoso.com/v1/openapi.json. Jede Operation hat eine operationId, Beschreibungen, Schemata mit Beispielen und Fehlerantworten; Webhooks stehen unter webhooks. Diese Dokumentation baut ihre Referenz daraus.

Generierte Clients und Typen kommen am besten direkt aus der Spezifikation:

# The specification, without authentication
curl https://api.flavoso.com/v1/openapi.json -o flavoso-openapi.json

# Only the TypeScript types, no runtime (openapi-typescript)
npx openapi-typescript https://api.flavoso.com/v1/openapi.json -o flavoso-api.d.ts

# A complete client, e.g. Python (openapi-generator, needs Java)
npx @openapitools/openapi-generator-cli generate \
  -i https://api.flavoso.com/v1/openapi.json \
  -g python -o ./flavoso-client

Postman#

https://api.flavoso.com/v1/postman.json ist eine Postman-Sammlung (v2.1) mit jeder Anfrage, gebaut aus der Spezifikation. Sie hat zwei Variablen: baseUrl und accessToken.

# The Postman collection (v2.1), built from the specification
curl https://api.flavoso.com/v1/postman.json -o flavoso.postman_collection.json

# In Postman: Import › Link › https://api.flavoso.com/v1/postman.json
# Then set the collection variable accessToken to a test token (flv_at_...).
# baseUrl is preset to https://api.flavoso.com/v1

Für Sprachmodelle#

https://flavoso.com/llms.txt nennt die Dokumentation, die Spezifikation und die Postman-Sammlung in einer Form, die ein Sprachmodell liest. Wer sich Code von einem Assistenten schreiben lässt, gibt ihm am besten die Spezifikation.