Skip to content

Technology Design Docs Observability

mavrovde edited this page Nov 13, 2026 · 2 revisions

Technology: Design, Documentation and Observability

Part of the Technology Evaluation. The standards the API follows, the tools that produce and check its documentation, and the observability stack.

Summary

Area Recommended Viable Rejected
OpenAPI generation code-first from types (huma for Go, utoipa for Rust); exported file committed and diffed spec-first generators for client code; typed client generation for examples spec-first as the source of truth for the server (a second source of truth)
Reference rendering Scalar Redoc Stoplight Elements
Guide a static documentation site (Astro Starlight) beside the reference
OpenAPI lint Spectral with project rules
Breaking-change detection oasdiff
Telemetry OpenTelemetry, minimal and manual; loopback Prometheus endpoint Prometheus and Grafana containers at the first stage
Standards RFC 9457, RateLimit header draft, RFC 9745, RFC 8594, RFC 7946 OAuth 2.1 client credentials later

OpenAPI generation

  • Code-first generation from the types the handlers already use means there is one source of truth. The exported document is committed, linted and compared against main on every pull request.
  • Spec-first generators (for example oapi-codegen or OpenAPI Generator) are useful for clients, not for the server.
  • Verdict: Recommended: code-first.

Scalar

  • An API reference renderer with a "try it" client; MIT; static and self-hostable with no backend; OpenAPI 3.1.
  • Verdict: Recommended.

Redoc

  • A mature, print-friendly three-panel renderer; the open-source edition has no "try it" panel.
  • Licence. MIT. Verdict: Viable alternative.

Stoplight Elements

  • An embeddable documentation component; development has slowed since its acquisition.
  • Licence. Apache-2.0. Verdict: Rejected in favour of Scalar.

Spectral

  • A rule-based OpenAPI linter. Project rules require a description, examples and attribution for every operation and refuse collection vocabulary and storage names.
  • Licence. Apache-2.0. Verdict: Recommended.

oasdiff

  • OpenAPI diff with breaking-change detection; one binary, run only in CI. A breaking change without a major version bump fails the pull request.
  • Licence. Apache-2.0. Verdict: Recommended.

OpenTelemetry

  • The vendor-neutral standard for traces, metrics and logs, with SDKs for every shortlisted language.
  • Automatic instrumentation adds memory and per-request overhead; the design prefers manual spans on the request, admission, use case, database call and cache, and metrics through a loopback Prometheus endpoint. A collector is optional.
  • Licence. Apache-2.0. Verdict: Recommended, minimal and manual.

Prometheus and Grafana

  • A metrics time-series database and dashboards.
  • New monitoring containers are not justified at the first stage; the API exposes /metrics on loopback and writes hourly usage to its own store, and ViaFrei's operator dashboards show it.
  • Licence. Apache-2.0 (Prometheus), AGPL-3.0 (Grafana). Verdict: Rejected as new containers now; revisit at a later stage.

Standards adopted

Standard Use
RFC 9457 Problem Details every error
IETF RateLimit header fields (draft) RateLimit and RateLimit-Policy on every response
RFC 9745 Deprecation announcing deprecated versions or operations
RFC 8594 Sunset the retirement date of a deprecated version
RFC 7946 GeoJSON application/geo+json responses
RFC 9111 HTTP Caching ETag, Cache-Control, 304
OAuth 2.1 (draft) client credentials later, once final; API keys first

Sources

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally