openapi-post-to-query
Convert OpenAPI 3.2 POST operations to query when they are read-like (search, filter, list) rather than mutations. Uses conservative, high-confidence transforms plus a "needs review" bucket via x-codemod-suggestion annotations.
Problem
In OpenAPI 3.2, query is the right verb for operations that:
- Are safe (no server state change)
- Are idempotent (same input → same effect)
- Need a payload for complex filter criteria that don't fit in query params
Many APIs incorrectly use POST for search/filter/list endpoints. This codemod identifies and converts them.
Solution
- Auto-convert when confidence score ≥ 7 and no mutation signals
- Annotate when score 4–6 with x-codemod-suggestion: "convert-post-to-query (score=X: reason)"
- Skip when mutation signals (201, Location, action verbs, etc.) or low score
Usage
bash
Or run the transform directly:
bash
Params
| Param | Type | Default | Description |
|---|---|---|---|
| convert_threshold | number | 7 | Min score to auto-convert POST → query |
| annotate_threshold | number | 4 | Min score to add x-codemod-suggestion |
| commit_per_step | boolean | false | Commit after each change-producing step |
| run_ai_step | boolean | false | Run AI step for ambiguous cases |
| publish_pr | boolean | false | Push branch and create PR (off by default) |
| main_branch | string | main | Target branch for PR |
| api_token | string | — | GitHub API token when gh CLI unavailable |
| pr_title | string | — | Optional PR title |
| pr_body | string | — | Optional PR body |
Metrics
- openapi-post-to-query:
- action: convert — POST converted to query (high confidence)
- action: annotate — x-codemod-suggestion added (needs review)
- action: skip — not converted (hard block or low score)
- reason — short explanation of signals
Tricky Cases (when to use run_ai_step=true)
- Ambiguous endpoints — POST with mixed read/mutation semantics
- Async job patterns — 202 with jobId/taskId (codemod skips, but review)
- Custom naming — operationIds or paths that don't match standard patterns
What Gets Fixed
Automated (high confidence)
- post: → query: when operationId matches search|query|filter|list|find|lookup|scan, path contains /search|/query|/filter, response has items/results/data, requestBody has filter keys, and only 200/206 responses
Annotated (needs review)
- x-codemod-suggestion added when score 4–6; human/tooling decides
Skipped
- 201, Location header, action verbs in description, mutation path patterns (/actions/, /execute, /run, etc.), mutation body keys (password, token, charge, etc.)
License
MIT