Documentation
¶
Overview ¶
Package httpapi is the registry's HTTP surface: two handlers, one for reading and one for publishing.
Two handlers, not one ¶
Publishing is privileged and reading is not. They are separate [net/http.Handler]s so that whoever wires authentication in front of them cannot accidentally give one the other's policy — a single handler discriminating on method is one `switch` away from an open write path, and the mistake is invisible in review.
Why not Confluent's API ¶
Confluent's Schema Registry is organised around a mutable subject whose versions accumulate and whose ids the registry assigns:
GET /subjects
GET /subjects/{subject}/versions
POST /compatibility/subjects/{subject}/versions/{version}
That is the direct opposite of a permanent identifier chosen by the publisher and refused if it changes. Adopting the endpoints would inherit a compatibility model, an id-assignment scheme and a subject concept this registry deliberately replaced, and buy no interoperability in return — nothing speaking Confluent's protocol works against ours once the addressing differs.
One idea is taken from it, because it is right: compatibility is an operation a caller asks for explicitly, rather than an implicit property of publishing. That is what the compatibility query parameter is.
The surface ¶
GET /schemas list every published identifier
GET /schemas/{name}/versions list the versions of one name
GET /schemas/{name}/{version} the schema itself, as raw bytes
PUT /schemas/{name}/{version} publish, body is the raw bytes
Schemas are served as their own bytes rather than wrapped in an envelope, so a JSON Schema is readable in a browser and a protobuf descriptor set is usable by anything that reads one. The language and the root message travel in headers.
Index ¶
Constants ¶
const ( // HeaderLanguage names the schema language: jsonschema or protobuf. HeaderLanguage = "X-Schema-Language" // HeaderRoot names the root message of a protobuf descriptor set. Absent // for JSON Schema, which is its own root. HeaderRoot = "X-Schema-Root" )
The headers carrying what is not in the body.
Variables ¶
This section is empty.
Functions ¶
func ReadHandler ¶
ReadHandler serves the read endpoints. Mount it wherever unauthenticated (or broadly authenticated) traffic is allowed.
func WriteHandler ¶
WriteHandler serves the publish endpoint. Mount it behind whatever authentication publishing requires, on a path the read handler does not serve.