Skip to content
Browserberg Browserberg

Protocol versioning and compatibility

How clients and servers negotiate the Browserberg protocol: majors exact, minors ordered, strict requests, loose responses and open output enums.

Last updated:

The compatibility rule

Client 1.1.0 x-browserberg-protocol Server 1.2.0 GET /health says so compatible major must match exactly -- a different major is a refusal (426) minor server ≥ client: a newer server may add fields you ignore patch always compatible in both directions enums output enums are OPEN: keep a default branch, always
One rule decides compatibility: majors match exactly, the server's minor is at least the client's, patches never matter.

Version 1.2.0 and negotiation

The protocol is at version 1.2.0, versioned independently of the server and of every SDK. Compatibility follows one rule: major versions must match exactly, the server's minor must be at least the client's, and patch versions are always compatible.

Send the optional x-browserberg-protocol header to state your client's version. An incompatible pairing is refused with 426 protocol_incompatible rather than half-working — negotiating is not the same as working.

Check the server's version

`GET /health` requires no API key and reports the protocol version the server speaks — the number your client compares its own against.

curl -s "https://browserberg.com/health" | python3 -m json.tool

Strict requests, loose responses

The two directions are deliberately asymmetric. Requests are strict: a field the schema doesn't know — a typo, most often — is a 400 invalid_request, not something silently ignored while you wonder why an option had no effect. Responses are loose: a newer server may add fields your client has never seen, and your client must tolerate them.

The same tolerance applies inside values. Output enums are open, so always keep a default branch for members you don't recognise: 1.2.0 added idle_timeout to shutdownReason, and clients that matched exhaustively broke while tolerant ones never noticed.