Align entity write endpoints with request bodies + author entity resource in OpenAPI spec

[dmccoystephenson]

Summary

• Switches the entity write endpoints off the path-variable anti-pattern onto request-body DTOs, mirroring the already-aligned environment endpoints:
  • POST /api/v1/entities/{name} → POST /api/v1/entities with a CreateEntityRequest body.
  • PATCH /api/v1/entities/{id}/name/{name} → PATCH /api/v1/entities/{id}/name with an UpdateEntityNameRequest body.
• Adds CreateEntityRequest / UpdateEntityNameRequest DTOs with @NotBlank validation (mirrors CreateEnvironmentRequest / UpdateEnvironmentNameRequest).
• Authors the entity resource in docs/openapi/viron-api.json — it previously had no entity paths at all. Added all entity paths (list, by-id, by-environment/grid/location, unassigned, create, delete, rename) plus the two request schemas, and added the missing creationDate field to EntityDTO.
• Corrects the environment POST response status in the spec from 200 to 201 to match the controller's @ResponseStatus(CREATED) (spec discrepancy explicitly tracked under Align entity write endpoints with request bodies + add entity resource to OpenAPI spec #135).
• Updates the Python client (entityService) to send JSON bodies for create/rename, keeping the Java and Python clients parallel.

Test plan

• mvn test (Java 21) — passes; EntityControllerTest updated to body-based requests + added blank-name validation tests for both write endpoints (now inherit @WithMockUser from the Endpoints are unauthenticated over plain HTTP; RFC 0001 specifies JWT auth over HTTPS #149 auth merge).
• pytest (Python 3.11) — 80 passed; test_entityService updated to assert JSON-body calls.
• DTO boundary preserved (controller returns EntityDto only); endpoints now match the spec.

Notes

• This branch is based on current main (includes the Endpoints are unauthenticated over plain HTTP; RFC 0001 specifies JWT auth over HTTPS #149 JWT-auth merge / PR feat(security): require JWT authentication on the Viron API (#149) #150); diff is scoped to the 7 entity/spec files only.
• Touches the wire contract (docs/openapi/viron-api.json), so this is intentionally not auto-merged and needs human review.
• Out of scope (filed separately): the EnvironmentDTO spec schema is itself stale (width/height instead of creationDate).

Closes #135

[dmccoystephenson]

Self-review rubric (adversarial; CI is green on head as the external anchor):

Universal

• Scope: PASS — all 8 files serve #135 (entity write endpoints + entity resource in spec + the doc/test reflections). The one cross-resource line (env POST 200→201) is flagged inline as a judgment call.
• Tests-new: PASS — both changed write methods are exercised (createEntity_ReturnsCreated, updateEntityName_Success) and two new validation tests (createEntity_BlankName_ReturnsBadRequest, updateEntityName_BlankName_ReturnsBadRequest) cover the new @Valid behavior.
• Tests-fix: N/A — refactor, not a bug fix; new validation behavior is nonetheless covered.
• Sibling structure: PASS — CreateEntityRequest/UpdateEntityNameRequest mirror CreateEnvironmentRequest/UpdateEnvironmentNameRequest byte-for-byte in shape.
• Sibling renames: PASS — entity write endpoints brought in line with the already-aligned environment pair (#137).
• Docs: PASS — MVP.md line 57 (which explicitly tracked #135) marked implemented; spec authored; tickets.md/README/PLANNING/REBUILD_PLAN verified accurate. The stale Postman collection is the separate issue #136, deliberately untouched.
• Issue resolution: PASS — #135's named surface (entity write endpoints + 'add entity resource to viron-api.json') is fully changed.
• CI: PASS — build green on head c460b86.

Repo-specific

• DTO boundary: PASS — createEntity returns EntityDto via mapper; no internal model exposed.
• Spec alignment: PASS — every added entity path matches the controller (DELETE→204, POST→201, PATCH→200, relation GETs with correctly-named path params).
• Java/Python parallelism: PASS — entityService create_entity/update_entity_name updated to JSON bodies to match Java; both test surfaces updated and green (mvn test exit 0; pytest 80 passed on py3.11).
• Override correctness: N/A — no @OverRide added.

One non-blocking observation left inline. Not auto-merging: this PR edits the wire contract (docs/openapi/viron-api.json), which is on the do-not-auto-merge list — handing to a human reviewer.

[dmccoystephenson]

Judgment call (not part of the entity surface): changed the environment POST response from 200 to 201 to match the controller's @ResponseStatus(HttpStatus.CREATED). This spec discrepancy was explicitly tracked under #135's "Related spec discrepancy" note, so it's included here rather than left dangling. Flagging in case a reviewer prefers it split into its own change.

[dmccoystephenson]

Triage / skip reasons for this cycle (for auditability)

Picked: #135 (this PR). Deferred this cycle:

• Endpoints are unauthenticated over plain HTTP; RFC 0001 specifies JWT auth over HTTPS #149 — resolved independently during this cycle (merged as feat(security): require JWT authentication on the Viron API (#149) #150, JWT auth); this PR is rebased on top of it.
• Postman collection is wholesale stale (pre-rebuild GET-based paths) #136 (Postman collection wholesale stale) — depends on the entity resource now being in the spec; better done as a follow-up once Align entity write endpoints with request bodies + add entity resource to OpenAPI spec #135 lands so the regenerated collection matches the final contract.
• Wire OpenAPI-first codegen / spec-drift guard (rebuild-plan hygiene gap) #130 (OpenAPI-first codegen / spec-drift guard) — CI/devexp work, larger and not blocking; deferred.
• Replace ResultSet-returning DbInteractions.query with a RowMapper-style API returning List<T> #144 (RowMapper-style DbInteractions API) — large mechanical refactor across all four repositories; exceeds this cycle's scope ceiling.
• Add entity movement (move endpoint + validation), per RFC 0001 #146/Add collision / occupancy detection, per RFC 0001 #147/Support grid metadata, per RFC 0001 #148 (entity movement, collision detection, grid metadata) — net-new RFC-0001 features, larger than a single coherent cycle alongside Align entity write endpoints with request bodies + add entity resource to OpenAPI spec #135.

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Update: rebased onto latest main (now includes #150 JWT auth and #152 entity-movement/occupancy) and added one fix found during self-audit:

• The in-repo Java client SDK (services/EntityService.java) was still calling the old path-variable endpoints (POST /entities/{name}, PATCH /entities/{id}/name/{name}). Updated it to send CreateEntityRequest / UpdateEntityNameRequest bodies, mirroring EnvironmentService — so the Java and Python clients are both aligned (closes the gap flagged by viron-dev-loop#6).

CI green on the rebased head. Still not auto-merging — this PR edits the wire contract (docs/openapi/viron-api.json), so it's handed off for human review.

drafted by Claude on behalf of Daniel Stephenson