Repository navigation
Spec Quality Scenarios
Part of the Technical Specification. Requirement prefix: QAS. Corresponds to arc42 section 10, "Quality requirements", organised by the ISO/IEC 25010:2023 product quality model.
Each scenario has the six parts of the SEI scenario form: source, stimulus, artefact, environment, response and response measure. Every measure is a design target.
flowchart LR
Q[ViaFrei API quality] --> PE[Performance efficiency]
Q --> RE[Reliability]
Q --> SE[Security]
Q --> CO[Compatibility]
Q --> FS[Functional suitability]
Q --> IC[Interaction capability]
Q --> MA[Maintainability]
Q --> FL[Flexibility]
Q --> SA[Safety]
Priority for v1, highest first: security (licence correctness), reliability, performance efficiency, compatibility, functional suitability, maintainability, interaction capability, flexibility, safety.
| ID | Characteristic (ISO 25010) | Source and stimulus | Artefact and environment | Response | Response measure (design target) | Requirements |
|---|---|---|---|---|---|---|
| QAS-PERF-01 | Performance efficiency, time behaviour | A client asks for charging options near a point | Service at design load (A-CAP-1) | Answer with attribution | p95 ≤ 200 ms, p99 ≤ 500 ms | NFR-PERF-003 |
| QAS-PERF-02 | Performance efficiency, time behaviour | A client polls the same corridor every 30 s with If-None-Match
|
Normal operation, data unchanged |
304 without storage work |
p95 ≤ 10 ms; ≥ 95 % of polls are 304
|
PROT-041, NFR-PERF-005 |
| QAS-PERF-03 | Performance efficiency, resource utilisation | Sustained design load | One instance with its container limit | Serve within budgets | Memory stays below the stack's limit on [[Benchmark Plan | Benchmark-Plan]]; storage connections ≤ db.pool_max
|
| QAS-PERF-04 | Performance efficiency, capacity | A bulk client floods far above capacity | Overload | Shed bulk, protect critical | Critical p95 within target; bulk 429 with Retry-After within 50 ms; nothing past 2 s |
RATE-012, RATE-017 |
| QAS-REL-01 | Reliability, fault tolerance | A storage query hangs | Normal load | Cancel at the deadline | Answer by 2 s + 50 ms; backend idle within 200 ms; no poisoned connection reused in 1 000 runs | NFR-PERF-002, NFR-RES-007 |
| QAS-REL-02 | Reliability, fault tolerance | Storage becomes unavailable | Normal load | Open the breaker, refuse fast, serve permitted stale cache |
503 within 50 ms after the breaker opens; recovery within breaker.open_for + one probe after storage returns |
NFR-RES-002, NFR-RES-004 |
| QAS-REL-03 | Reliability, fault tolerance | One part of a route briefing times out | Normal load | Partial answer |
200 with the part timeout, the others ok, by the deadline |
FR-BRIEF-005 |
| QAS-REL-04 | Reliability, availability | Monthly operation | Production | Serve valid requests | ≥ 99.5 % without 5xx per 30 days |
NFR-AVAIL-001 |
| QAS-REL-05 | Reliability, recoverability | The instance is killed | Production | Restart and become ready | Ready within 30 s; at most one metering interval of counts lost | RATE-014 |
| QAS-SEC-01 | Security, confidentiality | A key whose plan excludes a family requests data that includes it | Any | Return only permitted families | 0 forbidden items served in the full gate test matrix; violation metric stays 0 | SEC-030 to SEC-033 |
| QAS-SEC-02 | Security, integrity | A cursor is tampered with | Any | Refuse |
400 invalid-cursor for 100 % of a fuzzed tamper corpus |
ENV-023 |
| QAS-SEC-03 | Security, authenticity | An attacker guesses keys | Internet | Refuse uniformly, rate limit | Identical 401 bodies; timing difference not significant at p < 0.01 over 10 000 tries; limited after auth.failure_limit
|
SEC-003, SEC-052 |
| QAS-SEC-04 | Security, accountability | The operator revokes a key | Several instances | Refuse the key everywhere | Within 5 s (design), at most auth.key_cache_ttl
|
SEC-042 |
| QAS-SEC-05 | Security, confidentiality | Keys are planted in headers, query strings and errors | Test | Nothing leaks to logs | 0 occurrences in every log sink | NFR-OBS-004 |
| QAS-COMP-01 | Compatibility, interoperability | A generated client from the published document | Any | Calls succeed | 100 % of documented examples validate against the document | VER-006 |
| QAS-COMP-02 | Compatibility, co-existence | API load peaks | Shared store | Other readers unaffected | API holds ≤ its connection share; no storage statement beyond the role timeout | NFR-CAP-002 |
| QAS-FUNC-01 | Functional suitability, correctness | Same input to an endpoint and its MCP counterpart | Fixtures | Same facts | 100 % fact equality in the parity suite | FR-GEN-002 |
| QAS-FUNC-02 | Functional suitability, appropriateness | A client displays an answer | Any | Attribution and notes present | 100 % of data responses carry attribution | LIC-001 |
| QAS-INT-01 | Interaction capability, learnability | A new developer with a sandbox key | Documentation portal | First successful call | Within 10 minutes following the getting-started guide (usability test with 5 participants) | DX-001 |
| QAS-INT-02 | Interaction capability, inclusivity | A screen-reader user reads the docs | Portal | Usable | WCAG 2.2 AA, no critical automated finding | NFR-A11Y-001 |
| QAS-MAINT-01 | Maintainability, modifiability | Storage renames an internal object | Read contract unchanged | No public change | 0 lines changed outside the storage adapter | NFR-MAINT-001 |
| QAS-MAINT-02 | Maintainability, modifiability | A new code value appears in storage | Production | Served as other, metric raised |
One mapping line to support it | ENV-051 |
| QAS-MAINT-03 | Maintainability, testability | A developer adds an endpoint | CI | Full test layers apply | Endpoint Definition of Done met in one pull request | TEST-010 |
| QAS-FLEX-01 | Flexibility, scalability | Load grows beyond one instance | Scale-out stage | Add instances | Only configuration and shared limiter state change | NFR-SCALE-002 |
| QAS-FLEX-02 | Flexibility, installability | Move to another host | Any OCI runtime | Run unchanged | Same image, configuration by environment only | NFR-PORT-001 |
| QAS-SAFE-01 | Safety, fail safe | Road or weather data is stale or missing in a briefing | Any | Do not signal "all clear" | Lamp unknown instead of green
|
FR-BRIEF-006, NFR-FRESH-002 |
| ID | Requirement | Verification |
|---|---|---|
| QAS-001 | Every scenario above MUST have an automated test or an operational measurement before the first public release, recorded in the traceability matrix. | Review |
| QAS-002 | A change that affects a scenario's measure MUST state the effect in its pull request. | Review |
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