Specification · 004-query-endpoint

Position query endpoint

A read-only HTTP endpoint to look up a current position.

Status Accepted Spec ID 004-query-endpoint Owner Platform team Reviewers — Created Principlesv1.0.0 Smallest demoableGET /positions/{instrument} returns the current quantity. Read time

A read-only query endpoint over positions. It reads through the adapter and touches no write path — unrelated to ADR-0007, one of the features that put distance between the decision and the reconciliation request.
I Independent
A self-contained feature in the position-keeper timeline.
N Negotiable
Outcomes contract; the mechanism is the design's.
V Valuable
Unlocks SC-001.
E Estimable
Plan derivable.
S Small
3 requirements.
T Testable
Observable via its success criterion.
Exec / PM
§Context, §Success criteria.
Reviewer
§Requirements, §Open questions.
Implementer
§Requirements, §Data model.

1 · Context

Downstream tools want to read a current position over HTTP. This endpoint is read-only; it does not mutate positions and does not touch ADR-0007. Its role in this example is distance — a merge that never mentions the decision.

2 · User scenarios & testing

Read a position. A GET returns the current quantity for an instrument.

Missing instrument. An unknown instrument returns 404.

3 · Requirements

The endpoint MUST return the current quantity for a known instrument. The endpoint MUST be read-only — it MUST NOT mutate any position. The endpoint SHOULD read through the existing adapter, not a new data path.
  • A history/time-series API — a later analytics feature.
  • Authentication — handled by the gateway.

4 · Data model

Position view
instrument + quantity, read-only projection.

5 · Success criteria

A GET returns the current quantity and no request path mutates a position.
Observed at

An HTTP test asserting the read result and the absence of any write.

6 · Assumptions

7 · Open questions

None outstanding.

8 · Conformance index

9 · Change log

  1. Status flipped Draft → Accepted on 18 Sep 2026 — zero remaining unchecked tasks (9/9); ./gradlew build green with PositionsEndpointTest (SC-001) verified passing and the process exercised with curl per author pre-confirmation for 003–007; contract promoted to api/positions.openapi.yaml. Sibling bundle (REQ-LIFECYCLE-005).
  2. Reset to Draft — re-driven through tasks → implement → verify against a real Gradle build; the 2024–25 dates in docs/timeline.md remain the narrated history.
  3. Accepted — read-only position query endpoint. Does not touch positions writes or ADR-0007.