PUT api configuration expansion

[eviltester]

PUT should have an api config option to amend an item on collection if the ID is present in payload i.e. PUT todos - {id:1,text="test"} to implement this add PUT options - locate by URI(mandatory or optional or disallow), payload include IDs (mandatory or optional or disallow)

locate by URI - configures what is allowed at the collection level - if mandatory then PUT todos would be disallowed, if optional then PUT todos and PUT todos/{id} would be allowed.

payload include ID - configures if a payload should include the locator id field - requests without the id would be rejected if mandatory (even if the locate by URI was mandatory), when optional then request would be allowed if they had all fields (excludng the id) and if allfields with id, when disallow requests would be rejected if they didn't have the id.

So in this scheme location is checked separately from payload.

This could lead to situations where id was disallows on uri and on body which would mean that PUT would not work - this should be flagged as a warning to the user - via some sort of validation function that returns a set of warnings and errors - the system should not allow api configurations with errors, but should allow api configurations with warnings, when there are no errors in te config.

[eviltester]

when done expand the buggy API and amend the API challenges to take advantage of this and make simple API pick one scheme

[eviltester]

PUT API Configuration Expansion

Summary

Add core Thingifier support for configurable PUT identity rules while preserving current defaults: URI identifier is mandatory, payload identifier is optional. First pass covers core Thingifier behavior only, not buggy API, API challenges, or simple API model updates.

Key Changes

• Add a PUT identifier policy enum with MANDATORY, OPTIONAL, and DISALLOWED.
• Extend entity write-method config with two global PUT policies:
  • URI identifier policy, default MANDATORY.
  • Payload identifier policy, default OPTIONAL.
• Use identifier naming in the public API, not “ID”, so the feature works cleanly for GUIDs, IDs, and custom primary keys.
• Add fluent config methods similar to existing write-method configuration, for example:
  • putIdentifierInUri(MANDATORY)
  • putIdentifierInPayload(OPTIONAL)
• Copy the new settings in profile/config setFrom paths.

Behavior

• Preserve existing behavior by default:
  • PUT /todos/{id} works.
  • PUT /todos remains rejected.
  • Payload may include the primary key, but does not have to.
• Allow collection-level PUT when URI identifier policy is OPTIONAL or DISALLOWED, resolving the target identifier from the payload primary-key field.
• Reject payloads that omit the primary key when payload identifier policy is MANDATORY, even if the URI contains the identifier.
• Reject payloads that include the primary key when payload identifier policy is DISALLOWED.
• If URI and payload identifiers are both present and differ, keep the existing 422-style mismatch behavior.
• Keep existing putCan(CREATE/UPDATE) semantics: once the identifier is resolved, PUT still creates or updates according to the configured allowed operations.

Validation And Docs

• Add an API config validation report with errors and warnings, mirroring the existing report style.
• Flag “URI identifier disallowed + payload identifier disallowed + PUT enabled” as a warning, not an error, because the issue explicitly allows warning-only configurations.
• Add the report at core config level, with warnings allowed and errors blocking request handling/docs generation if future error cases are added.
• Update generated API docs/Allow headers so collection and instance PUT support reflects the configured URI/payload policy.

Test Plan

• Unit-test config defaults and setFrom copying.
• Unit-test PUT routing/mapping for:
  • Default URI-only compatible behavior.
  • PUT /todos with payload identifier.
  • URI mandatory rejecting collection PUT.
  • URI disallowed rejecting instance PUT.
  • Payload mandatory rejecting missing body identifier.
  • Payload disallowed rejecting included body identifier.
  • URI/body mismatch returning the existing 422-style error.
• Unit-test interaction with putCan(CREATE), putCan(UPDATE), and putCan(CREATE, UPDATE).
• Unit-test validation report warnings for unusable PUT identity combinations.
• Unit-test generated docs and Allow headers for collection/instance PUT visibility.

[eviltester]

Work Done Summary

Implemented the core Thingifier PUT identifier policy expansion and merged it via PR #100.

Completed

• Added PutIdentifierPolicy with MANDATORY, OPTIONAL, and DISALLOWED.
• Added global entity write-method config for PUT identifier location:
  • URI identifier policy defaults to MANDATORY.
  • Payload identifier policy defaults to OPTIONAL.
• Added fluent config methods:
  • putIdentifierInUri(...)
  • putIdentifierInPayload(...)
• Copied the new settings through config/profile setFrom paths.
• Added core API config validation reporting with warnings and errors.
• Added the warning-only validation case for PUT enabled while URI and payload identifiers are both disallowed.
• Updated PUT request mapping so collection-level PUT can resolve the target from the payload primary-key field when configured.
• Enforced URI and payload identifier MANDATORY, OPTIONAL, and DISALLOWED behavior.
• Preserved the existing URI/body identifier mismatch behavior with the existing 422-style response.
• Preserved existing putCan(CREATE), putCan(UPDATE), and putCan(CREATE, UPDATE) semantics after identifier resolution.
• Updated generated docs and Allow-header behavior so collection and instance PUT availability reflects the configured identifier policies.
• Preserved primary-key values during replacement PUTs when payload identifiers are optional or disallowed.
• Tightened identity mismatch detection for custom/string primary keys as well as generated IDs/GUIDs.

Tests Added/Updated

• Config defaults and setFrom copying.
• Default URI-only compatible PUT behavior.
• Collection PUT using payload identifier.
• URI mandatory rejecting collection PUT.
• URI disallowed rejecting instance PUT.
• Payload mandatory rejecting missing body identifier.
• Payload disallowed rejecting included body identifier.
• URI/body mismatch returning the existing 422-style error.
• putCan(CREATE), putCan(UPDATE), and putCan(CREATE, UPDATE) interactions.
• Validation report warnings for unusable PUT identity combinations.
• Generated docs and Allow-header visibility for collection/instance PUT.

Validation

• Focused tests passed: mvn -pl thingifier -Dtest=WriteMethodsConfigTest,ThingWriteRequestMapperTest,WriteMethodPolicyTest test — 52 tests passed.
• Full module tests passed: mvn -pl thingifier test — 485 tests passed.
• GitHub PR checks passed for PR Add configurable PUT identifier policies #100: Java formatting, Java 17 execution, and Java 21 execution.
• Local mvn -pl thingifier verify reached existing Checkstyle project-rule violations outside this change; tests, packaging, formatting, and coverage completed before that Checkstyle stop.

Merged in PR #100: #100