first commit

docs/adr/0015-use-full-replace-put-no-patch.md

@@ -0,0 +1,49 @@
+# 0015. Use Full-Replace PUT as the Partial Update Strategy
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+HTTP defines two methods for updating an existing resource:
+
+- **PUT** — full replacement; the client sends the complete resource
+  representation, and the server replaces the stored state entirely
+- **PATCH** — partial update; the client sends only the changed fields
+
+Both are standard and well-understood. The choice affects API surface
+complexity, client implementation requirements, and server-side
+validation logic.
+
+## Decision
+
+We use PUT for all player update operations
+(`PUT /players/squadNumber/{n}`). The request body must contain the
+full player representation; the server replaces the stored resource
+entirely. No PATCH endpoint is provided at this time. A PATCH
+implementation is tracked in the project backlog and remains under
+active consideration.
+
+## Consequences
+
+### Positive
+
+- Simpler server-side implementation: a single validation path,
+  no partial-update merge logic
+- PUT semantics are idempotent and well-understood by API consumers
+- Consistent with all sibling repos in the cross-language comparison set
+
+### Negative
+
+- Clients must send the full resource representation even for
+  single-field changes
+- Fine-grained partial updates require a GET followed by a full PUT
+- PATCH tracked in backlog — if implemented, this ADR will be superseded
+
+### Neutral
+
+- Standard REST semantics; no ambiguity about the update contract
+  for current consumers