Add velocity-api: the OpenAPI 3.1 contract (source of truth) - #6
Merged
Conversation
The authoritative HTTP API document (AR-1); DTOs/clients are generated from it downstream (openapi-generator, AR-3). OpenAPI-first — no hand-written DTOs. - velocity-engine-api.yaml (OpenAPI 3.1.0): endpoints record/query/capabilities/ features/purge (AR-2, FR-6/23/41), each namespace-scoped; API-key security (X-API-Key, P9) with namespace-scoped-authz 403 documented (NFR-21); RFC 9457 application/problem+json errors with 8 distinct types mapping to FailureCode + NFR-19/NFR-22 (deadline-exceeded, overloaded, unavailable, unsupported-window, ...). - Wire schemas faithfully mirror the frozen SPI model (FeatureResult as a discriminated Success|Failure oneOf — the ADR-0009 no-silent-0 branch; FeatureValue, ApplyResult/PerFeature, BackendCapabilities, Aggregation, Window). - Resolves OQ-D: money AND every numeric `value` field are JSON strings of a decimal integer (^-?\d+$) — matches BigDecimal scale-0 cents, avoids JSON-number precision loss (>2^53) and float coercion in generated clients. requirements §13 OQ-D marked resolved. - OpenApiSpecTest (swagger-parser): asserts the spec parses with ZERO messages, is 3.1, declares all five endpoints, money/value are integer-strings, FeatureResult is a discriminated oneOf, and X-API-Key is global. 9 tests. - build.gradle.kts: dropped unused jackson/jspecify (OpenAPI-first, no DTOs); added swagger-parser test-only to the catalog. Validated by the change-validator agent: VERDICT APPROVE (zero SPI drift, valid OpenAPI 3.1, no changes required). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
velocity-api— the committed OpenAPI 3.1 document that is the single source of truth for theHTTP API (AR-1). OpenAPI-first: DTOs and the Java client are generated from this yaml downstream
(
openapi-generator, AR-3), so there are no hand-written DTOs to drift.What's in it
velocity-engine-api.yaml(OpenAPI 3.1.0) — endpointsrecord/query/capabilities/features/purge(AR-2; FR-6/23/41), all namespace-scoped; API-key security (X-API-Key,P9) with namespace-scoped-authz
403documented (NFR-21); RFC 9457application/problem+jsonerrors with 8 distinct problem types mapping to
FailureCode+ NFR-19/NFR-22.velocity-spimodel exactly, includingFeatureResultas a discriminatedSuccess | FailureoneOf (the ADR-0009 "never a silent 0"branch),
FeatureValue,ApplyResult/PerFeature,BackendCapabilities,Aggregation,Window.The validator cross-read every schema and found zero drift.
recordrequest takes rawdimensions— the service keyed-hashes them (FR-38); pre-hashedmembers correctly never appear on the wire.
Resolves OQ-D (wire money representation)
Money and every numeric
valuefield (counts, cardinalities, sums) are JSON strings of adecimal integer (
^-?\d+$). This matches the SPI'sBigDecimalscale-0 cents and avoidsJSON-number precision loss (>2⁵³) and float coercion in generated clients. requirements §13 OQ-D is
flipped 🔴 → ✅.
Test
OpenApiSpecTest(swagger-parser) — asserts the spec parses with zero messages (not just "noexception"), is 3.1, declares all five endpoints, money/value are integer-strings,
FeatureResultisa discriminated
oneOf, andX-API-Keyis global. 9 tests; would fail if an endpoint were dropped ormoney became a number.
Review
Reviewed by the
change-validatoragent (CLAUDE.md working model): VERDICT APPROVE — validOpenAPI 3.1, zero SPI drift, money encoding consistent everywhere, all problem types + security
present, test not weakened. No changes required.
./gradlew :velocity-api:build→ BUILD SUCCESSFUL.🤖 Generated with Claude Code