Ensure API configuration endpoints (e.g., PUT /api/config) define and enforce a precise request/response contract across schema shape, merge semantics, validation behavior, and persistence.
Apply this standard:
Schema must match canonical payload serialization. For complex/credential fields, your JSON Schema should validate the exact shape your server produces/round-trips (e.g., secret references). Validate with the same Draft/validator behavior used in production.
Strict validation with no state change on rejection. If a payload is invalid (unknown enum, incompatible sub-objects, wrong auth-mode config), return 400 and guarantee the config is not mutated.
Explicit partial-merge vs reset semantics. If the endpoint performs a partial merge, omitted fields must preserve existing stored values (do not “default reset”). Document this behavior and test it.
Test the contract end-to-end. Add E2E tests that:
PUT invalid config ⇒ 400 and assert GET round-trip shows no change.
PUT valid config ⇒ GET confirms persistence.
When behavior is mode-dependent, assert the correct branch (and that security flips only when intended).
Example (server-side merge rule pattern):
// Only update each field when explicitly provided so partial PUTs do not clear stored values.ifpayload.ClientConfig.MCPServerAuthMode!=""{updatedConfig.MCPServerAuthMode=payload.ClientConfig.MCPServerAuthMode}// otherwise keep currentConfig.MCPServerAuthMode
Example (E2E assertion pattern):
PUT invalid payload ⇒ expect 400 and response text includes the relevant field name.
Then GET /api/config and assert the boot/auth mode equals the preexisting value (round-trip persistence).