📖 4 min read (~ 700 words).

Features

A primer on what this runtime implementation supports, with normative references to the standards each feature implements. Citations point at the canonical specification rather than secondary sources.

Client & Server

  • HTTP/1.1 and HTTP/2 over plaintext or TLS. HTTP/2 is inherited transparently from Go’s net/http stack on both client and server when ALPN negotiates h2; no runtime-specific wiring. See HTTP core below for the supporting RFCs.
  • Content negotiation on Accept / Accept-Encoding, honouring MIME parameters and quality values (RFC 9110 §12, §12.4.2 quality values).
  • URI templating for path-parameter expansion (Level-1 simple expansion only) per RFC 6570; values are percent-encoded per RFC 3986 §2.
  • Structured-suffix MIME matching — e.g. application/vnd.acme+json falls back to the application/json codec (RFC 6838 §4.2.8, IANA structured-syntax-suffix registry).
  • Routing against an analyzed OpenAPI specification.
  • Predefined codecs:
    FormatReference
    JSONRFC 8259
    XMLW3C XML 1.0 (via Go encoding/xml)
    CSVRFC 4180
    text/plainRFC 2046 §4.1
    Byte streamapplication/octet-stream — RFC 2046 §4.5.1
    YAMLYAML 1.2 (via the yamlpc sub-package)
  • Parameter binding for every OpenAPI parameter location:
    • Path parameters with URI Template Level-1 expansion (RFC 6570).
    • Query parameters.
    • Header parameters.
    • Request body decoded through the matched Consumer.
  • Streaming bodies:
    • File upload via multipart/form-data (RFC 7578) or application/x-www-form-urlencoded (WHATWG URL).
    • Other streams via application/octet-stream (RFC 2046 §4.5.1) or any custom MIME, surfaced as io.Reader / io.Writer.

Trailing-slash behaviour

  • Strictly preserved by the client — the path supplied by the caller is passed through verbatim.
  • Ignored by the server — a route declared as /pets matches both /pets and /pets/.

Optional, opt-in

  • Loosened content negotiation (negotiate.WithIgnoreParameters):
    • Strip MIME parameters before matching (application/json; charset=utf-8 → application/json).
    • Match the structured MIME suffix (application/vnd.acme+json → application/json).

Client

  • Configurable HTTP transport, TLS / mTLS (RFC 8446), proxy support per RFC 9110 §7.6.4.
  • Pluggable authentication writers (see Authentication).
  • Built-in OpenTelemetry tracing (OpenTelemetry spec); legacy OpenTracing support remains in a sibling compatibility module.
  • Debug mode — request / response dumping enabled via the Runtime.Debug field (or Runtime.SetDebug(true)); useful while iterating on a generated client.

Server

  • Composable middleware pipeline: Router → Security → Bind → Validate → OperationHandler → Responder.
  • Pluggable error rendering via api.ServeError.
  • Built-in doc-UI middleware: SwaggerUI, RapiDoc, Redoc.

Authentication schemes

The runtime parses the standard auth headers and dispatches to application-supplied callbacks for credential / token validation. Token issuance, JWT signature checking, and OIDC ID-token validation are out of scope — they belong in the callback.

  • HTTP Basic — header parsing per RFC 7617.
  • API Key in header, query, or cookie — OpenAPI security scheme convention; no dedicated RFC.
  • Bearer tokens — header parsing per RFC 6750. The runtime treats the bearer value as an opaque string; downstream parsing (JWT, opaque tokens, …) is the callback’s responsibility.
  • OAuth 2.0 — the runtime exposes the same Bearer hook with the OAuth-2 framing (RFC 6749; RFC 8252 for native apps). All four grant flows (authorization code, implicit, client credentials, password) work because the runtime sees only the resulting access token.

Not supported (yet)

  • Language negotiation — Accept-Language / Content-Language headers and language-tag parsing.
  • Compression — Accept-Encoding / Content-Encoding negotiation and the content-coding registry (gzip, Brotli, zstd).
  • HTTP caching — Cache-Control / ETag / Last-Modified / validators.

Normative references

OpenAPI specifications

HTTP core

URIs

Media types

Authentication

Tracing