Protokoll-Versionierung und Kompatibilität
Wie Client und Server das Browserberg-Protokoll aushandeln: exakte Majors, geordnete Minors, strikte Requests, tolerante Responses und offene Enums.
Zuletzt aktualisiert:
Die Kompatibilitätsregel
Version 1.2.0 und die Aushandlung
Das Protokoll steht bei Version 1.2.0 und wird unabhängig vom Server und von jedem SDK versioniert. Kompatibilität folgt einer Regel: Major-Versionen müssen exakt übereinstimmen, die Minor des Servers muss mindestens der des Clients entsprechen, und Patch-Versionen sind immer kompatibel.
Mit dem optionalen Header x-browserberg-protocol nennt dein Client seine Version. Eine unverträgliche Paarung wird mit 426 protocol_incompatible abgewiesen, statt halb zu funktionieren — aushandeln ist nicht dasselbe wie funktionieren.
Die Server-Version prüfen
`GET /health` braucht keinen API-Schlüssel und meldet die Protokollversion, die der Server spricht — die Zahl, mit der dein Client seine eigene vergleicht.
curl -s "https://browserberg.com/health" | python3 -m json.tool{
"ok": true,
"protocolVersion": "1.4.0"
}Strikte Requests, tolerante Responses
Die beiden Richtungen sind absichtlich asymmetrisch. Requests sind strikt: Ein Feld, das das Schema nicht kennt — meistens ein Tippfehler — ist ein 400 invalid_request und wird nicht stillschweigend ignoriert, während du dich wunderst, warum eine Option nichts bewirkt. Responses sind tolerant: Ein neuerer Server darf Felder ergänzen, die dein Client nie gesehen hat, und dein Client muss sie hinnehmen.
Dieselbe Toleranz gilt in den Werten. Ausgabe-Enums sind offen, also halte immer einen Default-Zweig für unbekannte Mitglieder bereit: 1.2.0 hat idle_timeout zu shutdownReason hinzugefügt, und Clients mit erschöpfendem Matching gingen kaputt, während tolerante nichts bemerkten.