Repository navigation
Technology Design Docs Observability
mavrovde edited this page Nov 13, 2026
·
2 revisions
Part of the Technology Evaluation. The standards the API follows, the tools that produce and check its documentation, and the observability stack.
| 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 |
-
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
mainon 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.
- An API reference renderer with a "try it" client; MIT; static and self-hostable with no backend; OpenAPI 3.1.
- Verdict: Recommended.
- A mature, print-friendly three-panel renderer; the open-source edition has no "try it" panel.
- Licence. MIT. Verdict: Viable alternative.
- An embeddable documentation component; development has slowed since its acquisition.
- Licence. Apache-2.0. Verdict: Rejected in favour of Scalar.
- 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.
- 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.
- 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.
- A metrics time-series database and dashboards.
- New monitoring containers are not justified at the first stage; the API exposes
/metricson 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.
| 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 |
- Scalar: https://scalar.com/solutions/openapi-documentation
- Redoc: https://github.com/Redocly/redoc
- Stoplight Elements: https://github.com/stoplightio/elements
- Spectral: https://docs.stoplight.io/docs/spectral/
- oasdiff: https://github.com/oasdiff/oasdiff
- Starlight: https://starlight.astro.build
- OpenTelemetry: https://opentelemetry.io/docs/
- Prometheus: https://prometheus.io/docs/; Grafana: https://grafana.com/docs/
- RFC 9457: https://www.rfc-editor.org/rfc/rfc9457
- RateLimit header fields: https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
- RFC 9745: https://www.rfc-editor.org/rfc/rfc9745; RFC 8594: https://www.rfc-editor.org/rfc/rfc8594
- RFC 7946: https://www.rfc-editor.org/rfc/rfc7946
- OAuth 2.1 draft: https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference