httpapi

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 8 Imported by: 0

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

View Source
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

func ReadHandler(r Reader) http.Handler

ReadHandler serves the read endpoints. Mount it wherever unauthenticated (or broadly authenticated) traffic is allowed.

func WriteHandler

func WriteHandler(p Publisher) http.Handler

WriteHandler serves the publish endpoint. Mount it behind whatever authentication publishing requires, on a path the read handler does not serve.

Types

type Publisher

type Publisher interface {
	Publish(ctx context.Context, s schema.Schema, mode schema.Compatibility) error
}

Publisher is the write half: privileged, and deliberately a different interface so a handler cannot be given both by accident.

type Reader

type Reader interface {
	Resolve(ctx context.Context, id urn.Schema) (schema.Schema, error)
	Versions(ctx context.Context, name string) ([]int, error)
	List(ctx context.Context) ([]urn.Schema, error)
}

Reader is the read half of the registry: everything safe to expose broadly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL