Skip to content

Make automatic path parameterization safer and configurable - #7

Open
alexchexes wants to merge 4 commits into
AndrewWalsh:mainfrom
alexchexes:fix/auto-parametrization
Open

Make automatic path parameterization safer and configurable#7
alexchexes wants to merge 4 commits into
AndrewWalsh:mainfrom
alexchexes:fix/auto-parametrization

Conversation

@alexchexes

@alexchexes alexchexes commented May 1, 2026

Copy link
Copy Markdown

Since this project is apparently discontinued, I have prepared a release (chrome extension only):
https://github.com/alexchexes/demystify/releases


Closes #5

The issue this fixes:

While capturing traffic in the Chrome extension, automatic path parameterisation could fold unrelated resource paths into templates like /api/{api}/... or
multi-parameter paths such as /api/{api}/{v2}/{param4}. That made the generated OpenAPI shape hard to use: stable resource names like /clients or /orders could disappear into path params.

The heuristics also could not be disabled or narrowed, so a bad fold was hard to recover from.

This PR:

  • Makes automatic folding more conservative:
    • ID-like path values (like /api/order/123, /api/order/234) can fold quickly, but only with compatible request and response shape evidence.
    • Query strings are stripped before matching path segments, so observed URLs such as /orders/1?include=... and /orders/2?include=... can still fold.
    • Text path values (like /api/foo, /api/bar) need 4 compatible observations.
    • Generic empty collection wrappers no longer trigger text folding by themselves.
  • Adds schema-shape compatibility for normal API variation:
    • scalar type changes are allowed;
    • null, empty objects, and empty arrays are treated as unobserved inside that branch;
    • real object/array/scalar conflicts block folding.
  • Stops folds from swallowing unrelated sibling routes and keeps existing parent endpoint data when child routes are folded.
  • Adds global parameterisation controls:
    • shared UI checkboxes (auto-folding, IDs, text routes, compatible shape matching).
    • CLI mode via --parameterisation safe-text|id-only|off;
    • library options on Representor;

It also fixes repo tooling so lint/typecheck/test/build can run normally on Windows.

Notes on design

The shape matcher is intentionally heuristic as before, but the risky parts are split into small checks so they are easy to adjust later. Sparse branches are neutral rather than positive evidence: an empty array or object does not prove item shape, but it also does not count all populated item fields as missing. Folding still requires at least some compatible observed fields.

Screenshots

Before:

chrome_2026-05-01--17-01-36--884

After:

image

Remaining limitation

The UI can rebuild parameterisation only from HAR entries captured or imported in the current session. Saved Demystify files don't contain raw HARs, so options changed via checkboxes apply only to future collected entries, not to the imported ones.

@AndrewWalsh

Copy link
Copy Markdown
Owner

Hi @alexchexes - thank you for taking the time to make these PRs, and really impressive work. I will review this later this week or the next.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Disabling / controlling path parameter imputation?

2 participants