Align write endpoints with spec: use request-body DTOs instead of path variables

[dmccoystephenson]

Summary

The write endpoints accept their inputs as path variables rather than request bodies, which diverges from docs/MVP.md and docs/openapi/viron-api.json. No controller currently uses @RequestBody.

Spec vs. implementation

Operation	Spec (MVP.md / OpenAPI)	Implemented
Create entity	POST /api/v1/entities with body	POST /api/v1/entities/{name} (path var)
Create environment	body CreateEnvironmentRequest	POST /api/v1/environments/{name}/{numGrids}/{gridSize} (path vars)
Rename environment	body UpdateEnvironmentNameRequest	PATCH /api/v1/environments/{id}/name/{name} (path var)

As a consequence, the two request DTOs named in MVP.md — CreateEnvironmentRequest and UpdateEnvironmentNameRequest — were never created (dto/ holds only response DTOs).

Proposed work

• Add CreateEnvironmentRequest and UpdateEnvironmentNameRequest DTOs with bean validation.
• Accept request bodies on the create/rename/create-entity endpoints (a CreateEntityRequest may be warranted).
• Decide whether the path-variable forms are kept for backward compatibility or removed; update docs/openapi/viron-api.json either way so spec and code agree.

Notes

A decision is needed on whether the spec or the current path-variable behaviour is authoritative; this issue assumes the spec is.

---

Filed by Claude on behalf of Daniel Stephenson.

[dmccoystephenson]

Deferred from the 2026-06-13 dev-loop cycle (which shipped #133, the EnvironmentRepositoryImpl tests). Skip reason: this issue requires a human decision on whether the OpenAPI spec or the current path-variable behaviour is authoritative, and it modifies the wire contract docs/openapi/viron-api.json — a do-not-auto-merge path. Better handled in a human-gated cycle.

[dmccoystephenson]

Resolved the environment portion in PR #137: POST /api/v1/environments and PATCH /api/v1/environments/{id}/name now take CreateEnvironmentRequest / UpdateEnvironmentNameRequest bodies (the two DTOs this issue noted were missing), matching docs/openapi/viron-api.json. The Java client SDK, Python client, controller/Python tests, and the MVP/PLANNING docs were all updated in lockstep.

The entity write endpoints (POST /api/v1/entities/{name}, PATCH /api/v1/entities/{id}/name/{name}) are the same anti-pattern but are not defined in the OpenAPI spec at all, so aligning them also requires authoring the entity resource in viron-api.json (a wire-contract change needing human review). To avoid an overly large PR and keep this issue's scope crisp, that work is split into #135.

Closing in favor of the split: environment done here, entity tracked in #135 (and the related 200-vs-201 spec discrepancy noted there). Pre-existing wholesale Postman drift is #136.