fix(published-rest): write an operation's query and body parameters, its mappings and its commit option (#571)

[ako]

Closes #571
Fixes mendixlabs#1206

What was wrong

create published rest service wrote only the path's {name} placeholders as operation parameters, each as a String. import mapping, export mapping and commit on an operation parsed, then were thrown away: the writer hard-coded them to "" / "" / Yes. The reader never read parameters, mappings or commit, so describe could not print them, and alter (which rewrites every operation) lost them too. The service writer also wrote constants for AuthenticationTypes, AuthenticationMicroflow, CorsConfiguration, Documentation and PublicDocumentation.

The worst case was executing describe output of a Studio Pro service. On TestApp's Services.OrdersRestApi it reported Modified, and a 0-error app went to 5 mx check errors:

• mappings cleared;
• Integer path parameters retyped as String (CE6539);
• body parameter dropped (CE0350);
• Commit changed from No to Yes;
• Basic and Session authentication turned off.

What Studio Pro stores (measured)

• TestApp Services.OrdersRestApi, Studio Pro 11.14:
  • Rest$RestOperationParameter holds Name, ParameterType (Path/Body), MicroflowParameter (Module.Microflow.Param), Description, and Type as the microflow parameter's own DataTypes$* (IntegerType; ObjectType with Entity);
  • ImportMapping / ExportMapping are qualified names;
  • list markers: Resources 3, Operations 2, operation Parameters 3, the service's empty Parameters [3], AuthenticationTypes a marker-1 string list.
• Studio Pro's metamodel schema, from ped_get_schema over the MCP tunnel:
  • commit: 'Yes' | 'YesWithoutEvents' | 'No', default No;
  • objectHandlingBackup: Create | Ignore | Error;
  • parameterType: Path | Query | Body | Header | Form;
  • the parameter type choices have no LongType, so Long is written as IntegerType, as the microflow writer does.

Fix

• Parameters are derived from the microflow, the way Studio Pro does it:

  • named in the path → Path;
  • an object or a list → Body;
  • System.HttpRequest / HttpResponse → none;
  • anything else → Query.

  Each parameter gets the microflow parameter's type. Derivation is merged over the stored parameters, matched on the bound microflow parameter. A header parameter, a renamed one or a described one set in Studio Pro keeps its name, kind and description, while its type follows the microflow. When the microflow does not exist yet, the operation keeps today's String path parameters and exec prints a warning.

• Mappings and commit go AST → model → BSON → reader. describe prints import mapping X export mapping Y, and commit Z when Z is not Yes. The visitor now builds quoted mapping names as qualified names instead of GetText().

• Refused instead of dropped:

  • an unknown commit option (commit Maybe) is refused by exec, and check reports it as MDL-REST03;
  • parameters MDL cannot state are noted in a describe comment, and create or modify / alter on that project keep them.

• Rewrites keep what MDL cannot state:

  • create or modify carries the restated operation's Summary, Documentation and ObjectHandlingBackup (matched by resource, method and path);
  • UpdatePublishedRestService carries the stored service-level keys above (keepStoredTopLevel, next to the ExportLevel carry).

• List markers are now the ones Studio Pro writes.

Design choices

• Default commit stays Yes. Studio Pro's default is No, but changing it would rewrite every operation mxcli has already created, and the language is frozen. describe prints commit whenever the stored value is not Yes, so the round trip is exact either way.
• No new syntax for parameters. Derivation matches Studio Pro, and the rare customizations are carried rather than spelled.
• ADR-0011: the new writes fix silent wrong writes, under both versions. MDL-REST03 refuses input that used to parse and be thrown away. There is no correct value to write for it.
• A service mxcli wrote before this fix gets one rewrite when its script is re-executed: list markers 2 → 3, and its derived parameters. After that it is a fixed point.

Test plan

• New unit tests, all green:
  • mdl/executor/cmd_published_rest_params_test.go:
    • parameter derivation for the create published rest service writes only path parameters: query and body parameters fail mx check (CE0350, CE6539) mendixlabs/mxcli#1206 repro (Query, Integer Path, Body object/list, HttpRequest skipped);
    • mapping and commit bindings, with quoted names;
    • unknown commit refused by exec and by check (MDL-REST03), with commit No as the control;
    • create or modify keeping a stored Header parameter, description, summary, documentation and object handling;
    • alter add resource deriving the new operation and leaving the old ones alone;
    • the missing-microflow warning;
    • describe printing bindings and notes, with its output re-parsing to the stored bindings.
  • mdl/backend/modelsdk/published_rest_write_test.go:
    • TestCreatePublishedRestService_WritesParametersAndBindings: write and read back every parameter field, the bindings, and the String path fallback;
    • TestWithStoredTopLevel, with an unlisted-key control.
• Revert checks. Each part of the fix was stubbed out in turn, and the named test failed with the reported symptom:
  • no derive in create → DerivesParameters, KeepsStoredParameters, MissingMicroflowWarns;
  • no carry → KeepsStoredParameters;
  • AST bindings dropped → WritesMappingBindings, DerivesAddedOperations;
  • describe without bindings → PrintsBindings;
  • commit not validated → RefusesUnknownCommit;
  • writer constants for the bindings → WritesParametersAndBindings, plus the TestApp round trip (ExportMapping: Services.OrdersExportMapping -> , Commit: No -> Yes);
  • no service-level carry → TestApp round trip (AuthenticationTypes: 3 -> 1 items);
  • old list markers → TestApp round trip (Resources[0]: 3 -> 2).
• Round-trip harness. The published rest service Services.OrdersRestApi entry is struck from the TestApp allowlist, so the allowlist shrinks. go test -tags integration ./mdl/roundtrip -run 'TestTestAppRoundTrip$|TestPedAppRoundTrip$' passes.
• mx check (11.14.0) on TestApp copies. The script was mdl-examples/bug-tests/571-published-rest-parameters-and-mappings.mdl (the create published rest service writes only path parameters: query and body parameters fail mx check (CE0350, CE6539) mendixlabs/mxcli#1206 repro plus an import/export-mapped operation), then a service on TestApp's real mappings, then describe → exec of Services.OrdersRestApi:
  • origin/main binary: 16 errors (CE0350 ×6, CE0354 ×5, CE6539 ×5);
  • this branch: 0 errors.
• Twice-exec (mdl 1): describe → exec of RestQ.Orders, Services.MappedApi and Services.OrdersRestApi reports Unchanged, twice, and no file under the project changes. A repeated alter … set Version writes nothing.
• go test -tags integration ./mdl/executor -run TestMxCheck_DoctypeScripts/22: mx check passes with 0 errors.
• go test ./mdl/executor ./mdl/backend/modelsdk ./mdl/visitor ./model ./cmd/mxcli ./mdl/conformance, make lint, make check-mdl, make check-conformance and make check-findings all pass.

Finding appended to .claude/skills/fix-issue/findings/mdl-executor.jsonl. Docs: mxcli syntax rest.published, docs-site/src/examples/rest-integration.md (it no longer says '{id}' requires $id: String), CHANGELOG.

🤖 Generated with Claude Code